Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tempinbox.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
Base URL

https://tempinbox.dev

​
Important: Cloudflare Turnstile

Temp Email 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 Temp Email 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: 
Authorization: Bearer <jwt>
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.
EndpointLimit
POST /api/new_addressStrict — Turnstile + IP rate limit
GET /api/mailsPer IP, per path
GET /api/mail/:uuidPer IP, per path
POST /api/switch_addressPer IP
DELETE /api/delete_addressPer IP
DELETE /api/clear_inboxPer IP
GET /api/settingsPer IP
GET /api/attachment/*Per IP
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

GroupDescription
AddressesCreate, inspect, and delete temporary email addresses
MailsList, read, and delete emails in an inbox
SessionManage up to 3 addresses per browser session
SystemHealth check

​
Response Format

All responses are JSON unless noted. Errors return plain text with an appropriate HTTP status code. 
// Success
{ "address": "[email protected]", "jwt": "eyJ..." }

// Error (plain text)
"Invalid domain"