Mail API Documentation

Start here

1. Get your personal API key from your service provider.
2. Keep your key private. Each user has a separate key and inbox access.
3. Use the key on your server with Authorization: Bearer YOUR_KEY.
4. Ensure an email domain and its Cloudflare Catch-all → Worker delivery are configured.

API keys are separate from the Worker delivery secret. Your key can access only the inboxes created for your API account. You cannot read another API user’s inboxes or claim existing personal inboxes. Your provider can rotate or disable your key without affecting other API users.

Download OpenAPI 3.0 schema

Endpoints

1. Get domains

BASE="https://YOUR-WEBSITE.com"
KEY="YOUR_API_KEY"
curl "$BASE/api/v1/domains" -H "Authorization: Bearer $KEY"

{"domains":["example.com"]}

2. Create an inbox

curl -X POST "$BASE/api/v1/mailboxes" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"username":"chen.wei482","domain":"example.com","password":"Choose-A-Strong-Password"}'

For a random address and password, send {"domain":"example.com"}. If domain is omitted, an available domain is selected randomly for each request. An explicit domain is respected. Passwords must contain 10–72 bytes. A successful create returns HTTP 201; an existing address returns 409. The password is returned only when created.

{"email":"chen.wei482@example.com","password":"…","expires":1790000000000,"url":"https://YOUR-WEBSITE.com/chen.wei482%40example.com"}

3. List messages

curl -G "$BASE/api/v1/messages" \
  -H "Authorization: Bearer $KEY" \
  --data-urlencode "email=chen.wei482@example.com" --data-urlencode "limit=50"

{"email":"chen.wei482@example.com","messages":[{"id":"64-character-id","from":"Sender <sender@example.org>","subject":"Verification code","text":"Your code…","received":1790000000000}],"next_cursor":null}

Limit: 1–100. Pass next_cursor back as cursor to fetch another page. An empty inbox returns an empty array. Poll every 3–5 seconds; received timestamps and expiry timestamps use Unix milliseconds.

4. Read HTML / delete

curl -G "$BASE/api/v1/messages/MESSAGE_ID" \
  -H "Authorization: Bearer $KEY" --data-urlencode "email=chen.wei482@example.com"

curl -X DELETE "$BASE/api/v1/messages/MESSAGE_ID?email=chen.wei482%40example.com" \
  -H "Authorization: Bearer $KEY"

Message detail returns id, email, from, subject, text, html, received. Treat received HTML as untrusted and render it in a sandbox. DELETE returns {"deleted":true}.

TMail-style routes

The four documented URL patterns are supported with your own API key. These are route-compatible examples; the upstream documentation does not publish an exact JSON response schema.

GET    /api/domains/{key}
GET    /api/email/{url-encoded-email}/{key}
GET    /api/messages/{url-encoded-email}/{key}
DELETE /api/message/{message-id}/{key}

Domains and messages return arrays; creation returns the inbox details with HTTP 201. The email-create route creates an inbox instead of merely validating a string. Keep URL keys out of browser history and logs; prefer the Bearer API for new integrations. Do not use the public demo as a production mail backend.

Limits and errors

120 requests / minute / API user 20 creates / minute / API user

Inbox lifetime: 24 hours. At most 100 messages are retained per inbox. Raw email size: 2 MB. The API does not send outgoing email. Disabled keys, missing credentials or rotated keys return 401. Unauthorized or expired inboxes/messages return 404; bad input 400; duplicate address 409; rate limit 429. Errors use {"error":"message"}. Keep access keys on your backend; no cross-origin browser access is enabled.

Contact your service provider for access, domain availability or delivery support.