Inboxes

All routes require bearer authentication. An inbox object has id, address, and created_at (ISO timestamp).

List inboxesCopy Anchor Link

GET /v1/inboxes returns 200:

{
  "inboxes": [
    {"id":"11111111-1111-4111-8111-111111111111","address":"my-agent@cherami.to","created_at":"2026-10-01T00:00:00.000Z"}
  ],
  "inbox_limit": 2
}

This list is not paginated. Ordinary accounts have a cap of two; use the returned inbox_limit as authoritative. List before creating, after recovery, or when an allocation response was lost. Agents should use the human's assigned inbox, not assume every listed inbox is theirs to take over.

Create an inboxCopy Anchor Link

POST /v1/inboxes

{"name":"my-agent"}

The required name normalizes to lowercase. It must contain 1–64 ASCII letters, digits, hyphens, or underscores and start and end alphanumeric. hello and test are reserved. Names are unique across accounts and retired addresses cannot be reused.

Returns 201 with the inbox object. 400 means invalid input. 409 covers an unavailable name or a reached account inbox cap. Choose another name if taken; do not create accounts to evade a cap. A lost response requires listing before retrying.

Delete an inboxCopy Anchor Link

DELETE /v1/inboxes/{inbox_id} returns 202:

{"id":"11111111-1111-4111-8111-111111111111","status":"deletion_pending"}

Permanently deletes the inbox and its received mail, sent copies, attachments, and threads, including unfinished messages. Confirm the specific inbox and destructive scope with the human before calling it, especially with shared access. This is agent guidance, not an additional API approval flow.

The slot is freed and the address is permanently retired. Future incoming mail is rejected. Retrieval and new sends from the deleted inbox return 404. Other inboxes and the credential remain unchanged. There is no undo or sending-quota refund.

Repeating DELETE is safe and can return 202 or 404. Missing or other-account resources also return 404. The service support inbox hello@cherami.to returns 409 protected_inbox to its owner.

Deletion guide and manual account deletion