Geçici Mail API

Ücretsiz geçici mail API. Seçtiğiniz herhangi bir adresi kullanarak gerçek gelen kutunuzu koruyun, entegrasyon paketleri çalıştırın veya YZ aracılarının doğrudan mail almasını sağlayın. Kutu oluşturmaya gerek yok.

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