TempFoxMail API

TempFoxMail is a disposable email service. The HTTP API lets you create inboxes, read incoming messages, extract one-time passcodes, and receive real-time delivery via WebSockets or webhooks. Anyone can use the anonymous web client without an account; developers use API keys, and registered users get server-side inbox history and cross-inbox search.

Base URL

All endpoints are served under the /v1 prefix:

text

https://api.tempfoxmail.com/v1

Authentication modes

Mode	Header / mechanism	Use for
Inbox token	`X-Inbox-Token: <capability_token>`	Anonymous access to a single inbox you created.
Bearer API key	`Authorization: Bearer tfm_live_…`	Developer access: create inboxes, register webhooks.
Session cookie	HttpOnly cookie (web only)	Account endpoints for registered users (history, search, keys).

Sending both a Bearer key and an inbox token in the same request returns 400 ambiguous_auth. An invalid Bearer key never falls back to anonymous access — it returns 401 invalid_api_key.

Error format

All errors share one envelope. The HTTP status matches the catalog code.

json

{
  "error": {
    "code": "inbox_not_found",
    "message": "Inbox does not exist or has expired.",
    "details": null
  }
}

A missing, foreign, or expired inbox is always 404 (never 403) so existence is never revealed.

Rate limits

Requests are rate-limited per client IP. When exceeded you receive 429 rate_limited with Retry-After and X-RateLimit-* headers. Login requests are additionally limited per email address.

Lifecycle & retention

Unregistered inboxes are short-lived and then physically deleted. Registered inboxes use a longer, operator-configured lifetime; after expiry they are archived (no longer receiving, but messages remain searchable) rather than deleted. Message HTML is always sanitized and served in a sandboxed iframe; remote content (tracking pixels) is stripped by default and only loaded opt-in through an image proxy so the reader's IP is never exposed.

OpenAPI

The complete machine-readable schema and an interactive explorer are available via Swagger UI at https://api.tempfoxmail.com/docs.