API Reference

Base URL

https://api.mail.cx/v1

All endpoints live under the /v1 prefix and require HTTPS. The base URL is the same for every request.

Authentication

Every request must carry an API token in the x-api-token header. The token kind determines what the caller can do:

• User token (tm_live_…) — Created from Dashboard → Tokens for SDK / automation. Subject to per-plan rate + monthly Ops quota. Free plan allows 1 user token, Pro 10.
• Web session (tm_live_…) — Minted by login / register / OAuth. 7-day TTL. Used by the browser UI; does not count against the user token quota and does not debit Ops.
• Anonymous (tm_anon_…) — Minted by POST /v1/sessions/anon (browser only when Cloudflare Turnstile is enabled). 24-hour TTL by default. Limited to system-domain mailboxes — cannot access custom domains, /me, /tokens, /domains, or admin routes.

curl https://api.mail.cx/v1/inbox \
  -X POST \
  -H "x-api-token: tm_live_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Quick start

1. Create a temporary inbox. With no body the server picks a random local-part on the default system domain. Returns the address and its expiry as a Unix-millisecond timestamp.

curl -X POST https://api.mail.cx/v1/inbox \
  -H "x-api-token: tm_live_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{}'

// → 201
{
  "address": "ab12cd@qabq.com",
  "expires_at": 1715706000000
}

2. Wait for mail with a long-poll. The server holds the connection up to 25 seconds. 200 means new mail; 204 means the hold timed out — just re-issue with the cursor returned in next_since.

curl "https://api.mail.cx/v1/inbox/ab12cd@qabq.com?since=0" \
  -H "x-api-token: tm_live_your_token_here"

// → 200
{
  "emails": [
    { "id": "uuid", "from_email": "sender@example.com", "subject": "...", "preview_text": "...", "created_at": "2026-05-14T12:00:00Z" }
  ],
  "next_since": "1715706012"
}

3. Fetch the full email (text body, HTML body, attachments metadata) by id.

curl https://api.mail.cx/v1/email/{email_id} \
  -H "x-api-token: tm_live_your_token_here"

Rate limits & Ops quota

Two layers run atomically on every authenticated request: a per-user sliding-window rate limit and a monthly Ops counter. Anonymous tokens have no application-layer rate limit — IP throttling happens at the edge.

Authenticated responses include X-Ops-Limit and X-Ops-Remaining headers. A 429 with body {"error":"rate_limit_exceeded"} also sets Retry-After (seconds); a 429 with body {"error":"ops_quota_exceeded"} resets on the 1st of next month UTC.

What counts as an Op?

Only Dashboard-created user tokens (kind=user) debit Ops. Web-session tokens (UI login) and anonymous tokens never count against the monthly quota.

• POST /v1/inbox and POST /v1/mailboxes — creating an address
• GET /v1/email/:id and GET /v1/emails/:id — reading a parsed email
• GET /v1/emails/:id/raw and /attachments/:index — downloading raw EML or attachments
• Listing inbox, SSE streams, /me, /ops, /config, auth and admin endpoints are NOT counted

Endpoints

Inbox (v1, AI-friendly)

Compact resource shape designed for AI agents and SDK usage. The GET endpoints are long-polled — the server holds the connection up to 25 seconds (config wait_seconds, fixed by the server, not the client). When new mail arrives or the hold elapses, it responds. 204 = timed out with no mail; 200 = at least one matching email; 429 = concurrent-cap reached (Retry-After header included).

POST /v1/inbox accepts an optional JSON body. All fields are optional.

Mailboxes (legacy, by address)

The original address-keyed resources, used by the web UI. Same data model as the v1 endpoints, returns paginated lists instead of long-polling.

Email content

API tokens

Manage user-kind tokens (kind=user). Web-session tokens (from login) are not listed and cannot be revoked through this endpoint — sign out instead. Free plan: 1 token. Pro plan: 10 tokens.

Custom domains (Pro)

Add a domain you own and receive mail on every address under it. Verification requires two DNS records: a TXT record _tempmail.<domain> with value tempmail-verify=<token>, and an MX record pointing to smtp.mail.cx. The background verifier polls every 5 minutes; pending domains time out after 72 hours.

Account & usage

Real-time push (SSE)

Real-time email events use Server-Sent Events (SSE) over plain HTTP. The browser EventSource API auto-reconnects with the Last-Event-ID header, which the server uses as a Redis Stream cursor to replay anything missed during the gap. Since EventSource cannot set custom headers, the token is passed as a query string.

Each new email arrives as an SSE event. Heartbeat keepalives are sent as comment lines (:ka <id>) every 30 seconds so proxies do not drop the connection.

const es = new EventSource(
  "https://api.mail.cx/v1/sse/user?token=tm_live_your_token_here"
);

es.addEventListener("email", (e) => {
  const data = JSON.parse(e.data);
  // { id, address, from, subject, preview }
});

// Heartbeat lines (":ka <last-id>") are surfaced as comments — no handler needed.
// On disconnect EventSource auto-reconnects and sends Last-Event-ID;
// the server replays any missed events from the Redis Stream.

Errors

Errors are JSON objects with a machine-readable "error" key. The HTTP status code carries the category.

{ "error": "rate_limit_exceeded" }