Skip to main content

​
Overview

​
Cloudflare Turnstile

POST /api/new_address requires a valid Turnstile token (cf_token) when Turnstile is enabled. This protects against automated address creation abuse. What this means for you:
Turnstile runs automatically in the TempInbox UI. No manual steps required.
The recommended approach for scripts and CI:
  1. Open tempinbox.dev in a browser
  2. DevTools → Application → Cookies → copy the jwt cookie value
  3. Use it as Authorization: Bearer <jwt> in your scripts
  4. The JWT lasts 7 days — reuse it across runs
If you run your own instance with CF_TURNSTILE_SECRET_KEY unset, POST /api/new_address works without a cf_token and returns a JWT directly:

​
JWT Auth

After obtaining a JWT, authenticate all mail endpoints:
JWTs are address-scoped. A JWT for [email protected] cannot access emails for [email protected]. Store one JWT per address in your test runner.
JWT lifetime: 7 days. After expiry, extract a fresh one from the browser.
When using the API from a browser on tempinbox.dev, cookies are set automatically:
  • jwt — address JWT, HttpOnly, SameSite=Lax, 7-day expiry
  • session_id — session identifier, HttpOnly, SameSite=Lax, 30-day expiry

​
Session Endpoints (No JWT Required)

These use the session_id cookie instead of a JWT:
  • GET /api/session/addresses — list all addresses in session
  • POST /api/switch_address — switch active inbox
  • POST /api/logout — clear session

​
No-Auth Endpoints

No authentication required:
  • POST /api/new_address — create address (Turnstile required unless disabled)
  • GET /health_check — service health

​
Rate Limits

All authenticated endpoints are rate-limited per IP. If you hit 429 Too Many Requests:
  • Add 2–3 second delays between poll requests on /api/mails
  • Avoid creating new addresses in tight loops
  • Reuse JWTs across test runs — a JWT is valid for 7 days