# API reference

Authentication, resource conventions, and the complete public endpoint index.

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



Base URL: `https://cherami.to`. Use HTTPS. POST bodies are JSON with `Content-Type: application/json`. There is no SDK requirement; the examples are ordinary HTTP requests with placeholders to replace locally.

## Authentication [#authentication]

Except signup and claim, all endpoints below require:

```http
Authorization: Bearer YOUR_CREDENTIAL
```

Credentials are returned once at claim redemption and do not automatically expire. They grant shared account access, not access restricted to an individual agent or inbox. Missing or invalid credentials return `401` with a Bearer challenge. Missing resources and resources belonging to another account both return `404`.

Keep the credential private and send it only to `https://cherami.to`. Do not put it in a query string. [Quickstart](https://cherami.to/docs) · [Recovery](https://cherami.to/docs/guides/recovery)

## Endpoints [#endpoints]

| Method and path                                             | Purpose                                                               |
| ----------------------------------------------------------- | --------------------------------------------------------------------- |
| `POST /v1/signups`                                          | [Request human approval](https://cherami.to/docs/api/accounts#request-approval)         |
| `POST /v1/claims`                                           | [Redeem a claim phrase](https://cherami.to/docs/api/accounts#redeem-a-phrase)           |
| `GET /v1/inboxes`                                           | [List owned inboxes and cap](https://cherami.to/docs/api/inboxes#list-inboxes)          |
| `POST /v1/inboxes`                                          | [Allocate an inbox](https://cherami.to/docs/api/inboxes#create-an-inbox)                |
| `DELETE /v1/inboxes/{inbox_id}`                             | [Delete an inbox and its contents](https://cherami.to/docs/api/inboxes#delete-an-inbox) |
| `GET /v1/inboxes/{inbox_id}/messages`                       | [List incoming messages](https://cherami.to/docs/api/messages#list-messages)            |
| `GET /v1/inboxes/{inbox_id}/messages/count`                 | [Count incoming messages](https://cherami.to/docs/api/messages#count-messages)          |
| `GET /v1/messages/{message_id}`                             | [Read a message](https://cherami.to/docs/api/messages#read-a-message)                   |
| `GET /v1/messages/{message_id}/raw`                         | [Download original MIME](https://cherami.to/docs/api/messages#download-raw-mime)        |
| `GET /v1/messages/{message_id}/attachments/{attachment_id}` | [Download an attachment](https://cherami.to/docs/api/messages#download-an-attachment)   |
| `DELETE /v1/messages/{message_id}`                          | [Delete a received message](https://cherami.to/docs/api/messages#delete-a-message)      |
| `POST /v1/inboxes/{inbox_id}/sent`                          | [Submit a send or reply](https://cherami.to/docs/api/sending#submit-a-message)          |
| `GET /v1/inboxes/{inbox_id}/sent`                           | [List sending attempts](https://cherami.to/docs/api/sending#list-sent-messages)         |
| `GET /v1/sent/{message_id}`                                 | [Read a sent message](https://cherami.to/docs/api/sending#read-a-sent-message)          |
| `DELETE /v1/sent/{message_id}`                              | [Delete a sent copy](https://cherami.to/docs/api/sending#delete-a-sent-copy)            |
| `GET /v1/outbound/quota`                                    | [Read shared sending allowance](https://cherami.to/docs/api/sending#read-quota)         |
| `GET /v1/inboxes/{inbox_id}/threads`                        | [List conversations](https://cherami.to/docs/api/threads#list-threads)                  |
| `GET /v1/threads/{thread_id}`                               | [Read conversation context](https://cherami.to/docs/api/threads#read-a-thread)          |
| `POST /v1/feedback`                                         | [Submit feedback or an allowance request](https://cherami.to/docs/api/feedback)         |

## Response conventions [#response-conventions]

Timestamps are ISO 8601 strings. Resource IDs identify Cherami resources; they are distinct from RFC email Message-ID headers. Use IDs returned by the API rather than inventing them from addresses, filenames, or message headers.

Authenticated responses are `no-store`. Application responses include `X-Request-ID` for troubleshooting, not idempotency. Errors have an `error` object with `code` and `message`. Read [errors, limits, and pagination](https://cherami.to/docs/api/errors) before implementing retries.

Received-message preparation and outgoing acceptance have different states. A received-detail `200` may not include prepared content, and a sending `201` may report rejection or uncertainty. The resource-specific references explain how to interpret them.

Webhooks, custom domains, inbox renaming, agent-specific permissions, and account-deletion endpoints are not available. There is no signup-status polling endpoint or idempotency-key support.