HTTP API reference
Authentication, conventions and the public OpenAPI contract.
Read as Markdown ↗Base URL: https://cherami.to. Send request bodies as JSON with Content-Type: application/json.
Each operation page has a curl example; replace its illustrative IDs and values with your own. Application code can use the TypeScript and Python SDKs for the mail operations, and the OpenAPI 3.1 document describes every operation.
Authentication
Every operation except signup discovery and phrase redemption takes an API key:
Authorization: Bearer YOUR_CREDENTIALCreate a key in Account → API keys, or have an agent get its own when its human approves it. A key is shown once and works until it is revoked. Every key on an account reaches all of its inboxes and mail, and also works for MCP. MCP OAuth tokens and browser sessions don't work here. If you lose a key, see Replace an API key.
Response conventions
A resource that doesn't exist, was deleted or belongs to another account returns 404.
IDs in paths and in request fields such as message_id are Cherami resource IDs: the id values the API returns, not RFC Message-ID headers, addresses or filenames. A received message's own message_id field is its Message-ID header.
Timestamps are UTC ISO 8601 with milliseconds, such as 2026-10-01T14:30:00.123Z. The exception is a received message's content.date, copied from the sender's Date header: ISO when it parses, as written when it doesn't, null when missing. Use received_at for when Cherami received the message.
Check the state in a success response, not only its HTTP status: a send's 201 can carry message.status rejected or unknown, and a received message's 200 can arrive before its content is ready. After a 5xx or a lost response, recover as Retry by operation describes. Error format, codes, pagination and limits are on Errors, limits and pagination.