# TempMail

> Receive-only disposable email API. Create a mailbox, read incoming messages and verification codes as JSON. No login and no API key are needed for the basic flow.

Base URL: https://www.tempmail.ai/api/v1
OpenAPI: https://www.tempmail.ai/api/v1/openapi.json
Human docs: https://www.tempmail.ai/doc

## 1. Anonymous flow (no login, no key) — start here

1. GET  https://www.tempmail.ai/api/v1/domains                 -> {"items":[{"domain":"..."}]}
2. POST https://www.tempmail.ai/api/v1/accounts  body {}        -> 201 {"id","address","password","expires_at"}
   Optional body fields: "domain" (from step 1), "password".
3. POST https://www.tempmail.ai/api/v1/token     body {"address","password"} -> {"token":"tm_box_...","expires_at"}
4. GET  https://www.tempmail.ai/api/v1/messages  header Authorization: Bearer tm_box_...
   -> {"items":[{"id","from","subject","verification_code","created_at",...}],"total"}
   Poll every 2-5 seconds until a message with verification_code appears.
5. GET  https://www.tempmail.ai/api/v1/messages/{id} for the full HTML/text body and attachments.
6. DELETE https://www.tempmail.ai/api/v1/accounts/{id} when done (optional; mailboxes expire after 24 hours).

Anonymous mailboxes: random address, 24h lifetime, 10 MB per mailbox, rate-limited per IP.
Do NOT send an "address" field in the anonymous flow; it returns 403 upgrade_required.

## 2. Pro flow: custom, long-lived addresses with an API key

Requires a tm_live_ API key whose owner has TempMail Pro ($14.99/month or $89.94/year ≈ $7.50/month).
Keys are created at https://www.tempmail.ai/developer. A key created on a free account gains Pro abilities automatically once the owner subscribes.

POST https://www.tempmail.ai/api/v1/accounts
  Authorization: Bearer tm_live_...
  Content-Type: application/json
  {"address":"signup-bot@<domain>","password":"<optional>"}
-> 201 same shape as anonymous, plus "private": true and "expires_at": null (no expiry while subscribed).
Then use POST /token and GET /messages exactly as in the anonymous flow.

With a Pro key and no "address", POST /accounts creates a random 24h mailbox using the key's higher limits.

## 3. Errors

All errors: {"error":{"code","message","request_id"}}. "message" says what to do next.
- 403 upgrade_required: The `address` field needs a Pro API key. Retry without `address` for a random 24h mailbox, or ask the account owner to subscribe at /pricing and retry with their tm_live_ key.
- 401 invalid_api_key: The Authorization key is missing, revoked or malformed. Create a new key at /developer, or drop the header to use the anonymous flow.
- 400 invalid_address: Use a full address like "name@domain". Local part: 1-64 chars of a-z 0-9 . _ -, starting and ending with a letter or digit, no "..".
- 400 domain_not_available: Pick a domain returned by GET /domains and retry.
- 409 address_reserved: This local part is reserved (e.g. admin, support, postmaster). Choose another local part.
- 409 address_taken: Someone holds this address right now. Choose another local part or domain.
- 409 address_cooling_down: This address was used recently and is locked to protect the previous owner. Choose another local part or domain.
- 409 private_inbox_limit_reached: The account already holds the maximum private addresses (10). Release one in the web app, or create a random mailbox instead.
- 429 rate_limit_exceeded: Wait for the number of seconds in the Retry-After header, then retry.
Other: 401 invalid_mailbox_token (get a new token via POST /token), 404 account_not_found / message_not_found, 503 service_unavailable (retry with backoff).

## 4. Limits

Anonymous: limited per IP (see https://www.tempmail.ai/doc#description/limits). Free-plan key: 5 req/s and 100 mailboxes/day.
Pro key: 20 req/s, 1000 mailboxes/day, up to 10 private addresses, 30-day message retention on private addresses, 100 MB account storage.
Responses carry X-RateLimit-Limit / Remaining / Reset; 429 responses carry Retry-After.

If Pro lapses: 7-day grace period (mail still arrives) -> frozen (new mail rejected, old mail readable) -> released after 90 days frozen. Renewing restores frozen addresses.

## 5. Rules

- Receive only: sending, replying and forwarding are not supported.
- Keep tm_live_ keys server-side; never put them in browser code.
- A tm_box_ token reads exactly one mailbox.