API

Base URL

https://api.mail.cx/v1

All endpoints live under /v1 and require HTTPS.

Authentication

Every request carries a token in the x-api-token header. Register an account, then create a token from Dashboard → Tokens. Tokens look like tm_live_… (72 chars).

curl https://api.mail.cx/v1/inbox/test@mail.cx \
  -H "x-api-token: tm_live_your_token_here"

Receive mail

Pick any local-part under one of the system domains (or a custom domain you own) and read the inbox. Nothing is created server-side — the SMTP gateway accepts mail for any address under a system domain, and the inbox endpoint just returns whatever is currently buffered. Mail lives for one hour.

Wait for the first email:

curl "https://api.mail.cx/v1/inbox/test@mail.cx" \
  -H "x-api-token: tm_live_your_token_here"

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

Real-time push (SSE)

Server-Sent Events over plain HTTP. The browser EventSource API handles reconnection and Last-Event-ID replay automatically. Pass the token as a query parameter — EventSourcecannot set custom headers.

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 }
});

Custom domains

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

Account

Rate limit

10 requests per second per user, enforced by a sliding-window counter in Redis. A 429 response with { "error": "rate_limit_exceeded" } sets a Retry-After header. Long-poll concurrency is separately capped (one in-flight wait per token, ten per address) to keep one client from holding the connection pool.