Create an inbox
POST /v1/inboxes
Read as Markdown ↗POST /v1/inboxes
Requires an API key: Authorization: Bearer YOUR_CREDENTIAL.
local_part becomes the address local_part@cherami.to. The address is permanent: it can't be renamed or moved to another domain. To move an agent to a new address, see Change your agent's email address.
name identifies the inbox within the account and isn't shown to recipients; sender_name is the display name recipients see on its mail. Both are optional, can be edited later and need not be unique.
Recover creation
Include an idempotency_key to make a retry safe. If the response is lost or you get a 5xx, repeat the request with the same key and the original payload within 24 hours of your first attempt: a match returns 200 with replayed: true and the inbox as it is now, and creates nothing new.
A request refused with 400, address_unavailable or inbox_limit_reached leaves its key unused. Use each key for one inbox, and don't switch to a new key or another address to get past an uncertain result.
After 24 hours, or without a key, list inboxes and look for the address before creating again: an unkeyed repeat of a creation that succeeded returns 409 address_unavailable.
Request body
JSON object, at most 4 KiB in total.
Schema: CreateInbox
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
local_part | Yes | string | The part before @cherami.to, lowercased: 1–64 letters, digits, hyphens or underscores, starting and ending with a letter or digit. Taken, reserved and retired addresses are unavailable. |
name | No | string or null | Identifies the inbox within the account; not shown to recipients. At most 256 UTF-8 bytes; null or blank means none. |
sender_name | No | string or null | Display name recipients see on the inbox's mail. At most 256 UTF-8 bytes; null or blank means none. |
idempotency_key | No | string | Your unique value for this one operation. Save it with the exact request before sending; repeating that request with the same key within 24 hours returns what the first one did instead of acting again. pattern: ^[A-Za-z0-9_-]{1,128}$ |
Unknown fields are rejected.
curl example
Supply CHERAMI_API_KEY privately.
Save the payload as request.json, replacing the example values.
{
"local_part": "my-agent",
"name": "Research",
"idempotency_key": "RETAIN_A_UNIQUE_CREATION_KEY"
}curl --silent --show-error --include --request POST \
"https://cherami.to/v1/inboxes" \
--header "Authorization: Bearer $CHERAMI_API_KEY" \
--header 'Content-Type: application/json' \
--data-binary @request.jsonResponses
HTTP 200
A retry matched an earlier request: this is that request's result as it is now. Nothing new was created or sent.
X-Request-ID: Identifies this request; include it when reporting a problem.Location: Relative URL of the resulting resource.
Content type: application/json.
All of these schemas apply.
Part 1
Part 2
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
replayed | Yes | true | |
idempotency_expires_at | Yes | string | When the key stops protecting retries. format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$ |
{
"id": "11111111-1111-4111-8111-111111111111",
"local_part": "my-agent",
"address": "my-agent@cherami.to",
"name": null,
"sender_name": null,
"created_at": "2026-10-01T00:00:00.000Z",
"replayed": true,
"idempotency_expires_at": "2026-10-02T00:00:00.000Z"
}HTTP 201
Created.
X-Request-ID: Identifies this request; include it when reporting a problem.Location: Relative URL of the resulting resource.
Content type: application/json.
All of these schemas apply.
Part 1
Part 2
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
replayed | No | false |
HTTP 400
invalid_json: Send a valid UTF-8 JSON object, not an array or scalar.
invalid_inbox: Creation takes only local_part, name, sender_name and idempotency_key; an edit takes at least one of name and sender_name, and nothing else.
invalid_local_part: Use 1–64 letters, digits, hyphens or underscores for local_part, starting and ending with a letter or digit.
invalid_name: Use plain text without control characters, at most 256 UTF-8 bytes after trimming. The message names the field.
invalid_idempotency_key: Use 1–128 ASCII letters, digits, hyphens or underscores.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
HTTP 401
unauthorized: Send a valid API key as Authorization: Bearer <key>. If the key stopped working, get a new one through recovery.
X-Request-ID: Identifies this request; include it when reporting a problem.WWW-Authenticate:"Bearer"
Content type: application/json.
HTTP 404
not_found: The resource does not exist or does not belong to this account. A reply or forward source must also be in the sending inbox.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
HTTP 409
address_unavailable: The address is in use, reserved or retired. Choose another local_part.
inbox_limit_reached: All inbox slots are in use; error.details.allowance has the counts. Use an existing inbox, or request more slots rather than deleting an inbox still in use.
idempotency_conflict: The key was first used with different input. To recover that request, repeat it with its original inbox and payload; a different request needs its own key.
idempotency_result_unavailable: The key already created an inbox, draft or send whose result has since been deleted. Nothing new was created or sent; do not repeat the request under a new key. If a sent message is still in Trash, restore it to read the outcome.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
HTTP 413
body_too_large: Reduce the JSON request to the operation's body limit.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
HTTP 415
unsupported_media_type: Send Content-Type: application/json.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
HTTP 500
internal_error: The operation failed. Retry a read; after a write the change may have happened, so recover as retry by operation describes.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
Schema: CreatedInbox
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
id | Yes | string | Cherami resource ID. |
local_part | Yes | string | |
address | Yes | string | |
name | Yes | string or null | |
sender_name | Yes | string or null | |
created_at | Yes | string | UTC timestamp with milliseconds. format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$ |
replayed | No | boolean | true when a retry matched an earlier request: the result is that request's, and nothing new was created or sent. |
idempotency_expires_at | No | string | When the key stops protecting retries. format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$ |
Schema: Error
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
error | Yes | object |
error fields
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
code | Yes | string | Code to handle. Handle a code you don't recognize by its HTTP status. |
message | Yes | string | Explanation of this case; its wording can change. |
Schema: InboxError
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
error | Yes | object |
error fields
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
code | Yes | string | Code to handle. Handle a code you don't recognize by its HTTP status. |
message | Yes | string | Explanation of this case; its wording can change. |
details | No | object |
details fields
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
allowance | Yes | InboxAllowance | |
increase_request | Yes | string | |
policy_url | Yes | string |
Schema: InboxAllowance
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
allowance | Yes | integer | minimum: 0 |
used | Yes | integer | minimum: 0 |
remaining | Yes | integer | minimum: 0 |
unit | Yes | "inbox_slots" |