List inboxes
GET /v1/inboxes
Read as Markdown ↗GET /v1/inboxes
Requires a Claim-issued API key: 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
Replace resource-ID placeholders with returned IDs. Supply CHERAMI_API_KEY through your private shell environment.
curl --silent --show-error --include --request GET \
"https://cherami.to/v1/inboxes" \
--header "Authorization: Bearer $CHERAMI_API_KEY"Responses
HTTP 200
Successful operation; inspect resource state and outcome fields.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
{
"inboxes": [],
"inbox_limit": 0,
"inbox_allowance": {
"allowance": 0,
"used": 0,
"remaining": 0,
"unit": "inbox_slots"
}
}HTTP 401
unauthorized: Provide a valid bearer credential. Use human-approved recovery if access is lost.
X-Request-ID: Support correlation ID, not an idempotency key.WWW-Authenticate:"Bearer"
Content type: application/json.
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.
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.
Schema: InboxList
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
inboxes | Yes | array of Inbox | |
inbox_limit | Yes | integer | Authoritative current cap. minimum: 0 |
inbox_allowance | Yes | InboxAllowance |
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
| 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
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
error | Yes | object |
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 · Download OpenAPI 3.1