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.

Inbox lifetime & limits

Every inbox is created with a short default lifetime and can be extended up to a hard maximum. Assigning (adopting) an existing inbox to a registered account automatically extends its validity to one year. The values below are the default configuration; a given deployment may be tuned differently.

Inbox	Default lifetime	Maximum lifetime
Unregistered	3 hours	24 hours
Registered — newly created	3 hours	365 days
Assigned to your account	365 days	365 days

A registered account may keep up to 10 active inboxes at once. Extending an inbox moves its expiry forward one step at a time, never past the maximum lifetime; once the maximum is reached you receive 422 ttl_limit_reached.

Retention & content security

Once an inbox's lifetime ends it expires and is no longer accessible. Registered inboxes are then archived (no longer active, but incoming mail is still retained and messages remain searchable through your account) 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.