API reference
Authentication, resource conventions, and the complete public endpoint index.
Read as Markdown ↗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
Except signup and claim, all endpoints below require:
Authorization: Bearer YOUR_CREDENTIALCredentials 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 · Recovery
Endpoints
| Method and path | Purpose |
|---|---|
POST /v1/signups | Request human approval |
POST /v1/claims | Redeem a claim phrase |
GET /v1/inboxes | List owned inboxes and cap |
POST /v1/inboxes | Allocate an inbox |
DELETE /v1/inboxes/{inbox_id} | Delete an inbox and its contents |
GET /v1/inboxes/{inbox_id}/messages | List incoming messages |
GET /v1/inboxes/{inbox_id}/messages/count | Count incoming messages |
GET /v1/messages/{message_id} | Read a message |
GET /v1/messages/{message_id}/raw | Download original MIME |
GET /v1/messages/{message_id}/attachments/{attachment_id} | Download an attachment |
DELETE /v1/messages/{message_id} | Delete a received message |
POST /v1/inboxes/{inbox_id}/sent | Submit a send or reply |
GET /v1/inboxes/{inbox_id}/sent | List sending attempts |
GET /v1/sent/{message_id} | Read a sent message |
DELETE /v1/sent/{message_id} | Delete a sent copy |
GET /v1/outbound/quota | Read shared sending allowance |
GET /v1/inboxes/{inbox_id}/threads | List conversations |
GET /v1/threads/{thread_id} | Read conversation context |
POST /v1/feedback | Submit feedback or an allowance request |
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 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.