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.

​
Overview

MechanismUsed forHow it’s set
Cloudflare TurnstileCreating new addressesRequired in browser; blocks raw API calls
JWT (Authorization: Bearer)Per-address inbox accessReturned by POST /api/new_address
jwt cookieBrowser clients (same-origin)Set automatically as HttpOnly cookie
session_id cookieMulti-inbox session managementSet automatically as HttpOnly cookie

​
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 Temp Email 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
# Use a pre-extracted JWT directly — no Turnstile needed
curl "https://tempinbox.dev/api/mails?limit=10&offset=0" \
  -H "Authorization: Bearer <your-jwt-here>"
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:
curl -X POST https://your-instance.com/api/new_address \
  -H "Content-Type: application/json" \
  -d '{}'
# Returns: { "address": "...", "jwt": "eyJ..." }

​
JWT Auth

After obtaining a JWT, authenticate all mail endpoints: 
GET /api/mails?limit=10&offset=0
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...
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