Temp Mail API
Free Temp Mail API — a Temporary Email API for disposable inboxes. Use any address you pick to protect your real inbox, run integration suites, or let AI agents receive mail directly. No mailbox to create.
# Setup
Base https://api.mail.cx/v1
Auth -H "x-api-token: tm_live_..." (Dashboard → Tokens)
# Endpoints
Substitute user@example.com / mail.example.com / <id> with your own values.
GET /v1/inbox/user@example.com long-poll one address (see below)
DELETE /v1/inbox/user@example.com clear every email at the address
GET /v1/email/<id> full parsed email (text + html + attachments)
GET /v1/email/<id>/raw original .eml stream
GET /v1/email/<id>/attachments/<i> download one attachment by zero-based index
DELETE /v1/email/<id> delete one email
GET /v1/sse/addr?address=&token= SSE push, single address
GET /v1/sse/user?token= SSE push, all owned addresses
POST /v1/domains add custom domain (body: { "domain": "..." });
returns DNS records to set
GET /v1/domains list custom domains + verify_status
DELETE /v1/domains/<id> remove custom domain
GET /v1/domain/mail.example.com long-poll every address under your domain
GET /v1/me long-poll across every owned address
GET /v1/config server config (public)
POST /v1/tokens create token (plaintext returned once)
GET /v1/tokens list tokens
DELETE /v1/tokens/<id> revoke token
# Long-poll behaviour (inbox, me, domain)
Designed for AI agents and signup-flow automation: call once and the server
blocks until mail arrives — no client-side polling loop. Mail is returned
newest-first.
200 with results as soon as mail arrives
204 if 25 s elapses with nothing new — just reconnect (a new wait starts)
429 if you exceed 1 concurrent wait per token (10 per address)
The 25 s hold is server-fixed; clients cannot override via ?wait=.
Query params (all optional):
since cursor from the previous response's "next_since"; only mail after this is returned
count return as soon as N new emails have arrived (default 1, max 50)
limit cap of emails per response body (default 20, max 50)
from filter — only mail whose From contains this substring
subject filter — only mail whose Subject contains this substring
# Example — wait for the next mail
# Replace example.com with a system domain (GET /v1/config returns the list)
# or a custom domain you own. The mailbox is implicit — nothing to create;
# mail starts buffering the moment the SMTP gateway accepts it.
ADDR="user@example.com"
TOKEN="tm_live_..."
# 1. Block for up to 25 s until a new mail lands.
curl "https://api.mail.cx/v1/inbox/$ADDR" -H "x-api-token: $TOKEN"
# → 200
# {
# "emails": [
# {
# "id": "...",
# "from_email": "...",
# "subject": "...",
# "preview_text": "...",
# "created_at": "..."
# }
# ],
# "next_since": "..."
# }
# 2. Fetch the full parsed body (text + html + attachments).
curl "https://api.mail.cx/v1/email/<id-from-step-1>" \
-H "x-api-token: $TOKEN"
# 3. Poll again, passing the cursor so you only get strictly newer mail.
curl "https://api.mail.cx/v1/inbox/$ADDR?since=<next_since>" \
-H "x-api-token: $TOKEN"
# Free with daily quota
Base 500 req / day
Invite +100 req / day forever, per accepted signup (share your /r/<code> link from Dashboard)
# Limits
10 req/s per token + 500/day base quota. Each referred signup permanently adds +100/day (stacks per invite).
5 req/s per IP for anonymous (no token).
1 concurrent long-poll per token, 10 per address. 25 s server-fixed hold.
Mail kept 1 h, then auto-deleted.
# Errors
JSON {"error":"<code>"} + HTTP status:
400 bad request | 401 invalid_token / authentication_required
403 account_disabled | 404 not_found
410 email_expired | 429 rate_limit_exceeded / daily_quota_exceeded / token_busy / addr_busy
440 session_expired | 503 sse_unavailable
# Custom domain
TXT _tempmail.<your> tempmail-verify=<token>
MX <your> smtp.mail.cx
Verifier polls every 5 min; pending domains time out after 72 h.