# List inboxes

GET /v1/inboxes

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



{/* Generated from apps/web/openapi. Edit the contract, not this file. */}

`GET /v1/inboxes`

Requires a [Claim-issued API key](https://cherami.to/docs/api#authentication): `Authorization: Bearer YOUR_CREDENTIAL`.

`GET /v1/inboxes` returns `200`.

This list is not paginated. Use the returned `inbox_limit` as authoritative. `inbox_allowance` reports the cap, occupied slots and remaining slots as a current snapshot, not a reservation. List before creating or when recovering an uncertain allocation. Agents should use the human's assigned inbox, not assume every listed inbox is theirs to take over.

## curl example [#curl-example]

Replace resource-ID placeholders with returned IDs. Supply `CHERAMI_API_KEY` through your private shell environment.

```sh
curl --silent --show-error --include --request GET \
  "https://cherami.to/v1/inboxes" \
  --header "Authorization: Bearer $CHERAMI_API_KEY"
```

## Responses [#responses]

### HTTP 200 [#http-200]

Successful operation; inspect resource state and outcome fields.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

[InboxList](#schema-inboxlist)

```json
{
  "inboxes": [],
  "inbox_limit": 0,
  "inbox_allowance": {
    "allowance": 0,
    "used": 0,
    "remaining": 0,
    "unit": "inbox_slots"
  }
}
```

### HTTP 401 [#http-401]

`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.

* `X-Request-ID`: Support correlation ID, not an idempotency key.
* `WWW-Authenticate`: `"Bearer"`

Content type: `application/json`.

[Error](#schema-error)

### HTTP 404 [#http-404]

`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 500 [#http-500]

`internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

[Error](#schema-error)

## Schema: InboxList [#schema-inboxlist]

| Field             | Required | Type                                     | Meaning and constraints                   |
| ----------------- | -------- | ---------------------------------------- | ----------------------------------------- |
| `inboxes`         | Yes      | array of [Inbox](#schema-inbox)          |                                           |
| `inbox_limit`     | Yes      | integer                                  | Authoritative current cap. `minimum`: `0` |
| `inbox_allowance` | Yes      | [InboxAllowance](#schema-inboxallowance) |                                           |

## Schema: Inbox [#schema-inbox]

| Field         | Required | Type           | Meaning and constraints                                                                                                              |
| ------------- | -------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `id`          | Yes      | string         | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value.                                                       |
| `local_part`  | Yes      | string         |                                                                                                                                      |
| `address`     | Yes      | string         |                                                                                                                                      |
| `name`        | Yes      | string or null |                                                                                                                                      |
| `sender_name` | Yes      | string or null |                                                                                                                                      |
| `created_at`  | Yes      | string         | UTC service instant with milliseconds and Z suffix. `format`: `date-time` `pattern`: `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$` |

## Schema: InboxAllowance [#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"` |                         |

## Schema: Error [#schema-error]

| Field   | Required | Type   | Meaning and constraints |
| ------- | -------- | ------ | ----------------------- |
| `error` | Yes      | object |                         |

### `error` fields [#error-fields]

| Field     | Required | Type   | Meaning and constraints                                                                       |
| --------- | -------- | ------ | --------------------------------------------------------------------------------------------- |
| `code`    | Yes      | string | Programmatic error code. Handle unrecognized codes by status and operation-specific recovery. |
| `message` | Yes      | string | Human-readable context, not a stable string to match.                                         |

[HTTP conventions, errors and pagination](https://cherami.to/docs/api/errors) · [Download OpenAPI 3.1](https://cherami.to/openapi.json)