# Inboxes

List, allocate, and permanently delete inboxes under the shared account credential.

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



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

## List inboxes [#list-inboxes]

`GET /v1/inboxes` returns `200`:

```json
{
  "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 inbox [#create-an-inbox]

`POST /v1/inboxes`

```json
{"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 inbox [#delete-an-inbox]

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

```json
{"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](https://cherami.to/docs/guides/deletion)