API Mail Tạm

API mail tạm miễn phí. Dùng bất kỳ địa chỉ nào để bảo vệ hộp thư thật, chạy bộ kiểm thử tích hợp, hoặc để tác nhân AI nhận mail trực tiếp. Không cần tạo hộp thư.

# 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.