Temporary email API
Create an inbox, retain its private token, and read incoming messages with an authorization header.
| GET endpoint | Response |
|---|---|
/v1/mail/new?ttl_seconds=3600 | 201: id, address, read_token, expires_at, receive_only |
/v1/mail/inbox/{id} | 200: message summaries, total, expiry |
/v1/mail/message/{message_id} | 200: plain text, inert HTML and attachment metadata |
Reads require Authorization: Bearer <read_token>. Tokens belong in headers, never URLs. Wrong, missing or expired inboxes return 401 or 404.
Limits and retries
Default lifetime: one hour. Choose 60–86,400 seconds. Each inbox holds up to 25 messages, subject to bounded message and total storage. Attachments are metadata only. Sending servers must use TLS.
Creation changes state. Retry-safe creation requires a caller-generated 32-byte unpadded base64url bearer token and an Idempotency-Key header. Reuse both with the same parameters. Ordinary repeated creation makes separate inboxes.
422: invalid parameters. 429: rate limited; respect Retry-After. 503: temporarily unavailable.