# HTTP API reference

Authentication, conventions and the public OpenAPI contract.

Source: https://cherami.to/docs/api



{/* Generated from apps/web/openapi. Edit the contract, not this file. */}

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](https://cherami.to/docs/typescript) and [Python](https://cherami.to/docs/python) SDKs for the mail operations, and the [OpenAPI 3.1 document](https://cherami.to/openapi.json) describes every operation.

## Authentication [#authentication]

Every operation except signup discovery and phrase redemption takes an API key:

```http
Authorization: Bearer YOUR_CREDENTIAL
```

Create a key in [Account → API keys](https://cherami.to/account/api-keys), or have an agent get its own when its human [approves it](https://cherami.to/docs/quickstart#ask-your-human-for-approval). 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](https://cherami.to/docs/mcp#connect-with-an-api-key). MCP OAuth tokens and browser sessions don't work here. If you lose a key, see [Replace an API key](https://cherami.to/docs/guides/recovery).

## Response conventions [#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](https://cherami.to/docs/api/errors#retry-by-operation) describes. Error format, codes, pagination and limits are on [Errors, limits and pagination](https://cherami.to/docs/api/errors).

## Operations [#operations]

* [Signup and approval](https://cherami.to/docs/api/access)
* [Inboxes and rules](https://cherami.to/docs/api/inboxes)
* [Received messages](https://cherami.to/docs/api/messages)
* [Labels](https://cherami.to/docs/api/labels)
* [Sending and allowance](https://cherami.to/docs/api/sending)
* [Saved drafts](https://cherami.to/docs/api/drafts)
* [Conversations](https://cherami.to/docs/api/threads)
* [Trash](https://cherami.to/docs/api/trash)
* [Webhooks](https://cherami.to/docs/api/webhooks)
* [Feedback](https://cherami.to/docs/api/feedback)