Skip to main content

​
Base URL

​
Important: Cloudflare Turnstile

TempInbox uses Cloudflare Turnstile to protect the POST /api/new_address endpoint from abuse. This means:
  • Browser-based use works automatically — Turnstile runs invisibly in the UI
  • Automated/API use requires a valid cf_token — you must solve a Turnstile challenge before creating an address
For developer and QA automation, the recommended approach is to use the TempInbox web UI to pre-create addresses, copy the JWT from the browser (cookies or response body), and then use that JWT directly in your scripts to call the mail endpoints. The mail endpoints (/api/mails, /api/mail/:uuid) do not require Turnstile.

​
Getting a JWT for automation

  1. Open tempinbox.dev in your browser
  2. An address is created automatically — the JWT is set as an HttpOnly cookie named jwt
  3. Open DevTools → Application → Cookies → copy the jwt value
  4. Use it as Authorization: Bearer <jwt> in your API calls
Alternatively, if Turnstile is disabled on a self-hosted instance, POST /api/new_address returns a JWT directly with no challenge.

​
Authentication

Most endpoints require a JWT bearer token:
See Authentication for full details.

​
Rate Limits

Rate limiting applies per IP on all write and read endpoints. Exceeded requests return 429 Too Many Requests. Recommendations for automation:
  • Add 2–3 second delays between poll attempts on /api/mails
  • Do not create new addresses in tight loops — reuse JWTs across test runs where possible
  • Use one inbox per test run, not one per assertion

​
Endpoint Groups

​
Response Format

All responses are JSON unless noted. Errors return plain text with an appropriate HTTP status code.