Discover labels
GET /v1/inboxes/{inbox_id}/labels
Read as Markdown ↗GET /v1/inboxes/{inbox_id}/labels
Requires a Claim-issued API key: Authorization: Bearer YOUR_CREDENTIAL.
GET /v1/inboxes/{inbox_id}/labels lists names currently used on undeleted received and sent copies in an owned, undeleted inbox.
Optional prefix restricts names by a literal, case-sensitive prefix, trimmed using label-name rules. Empty or omitted means all names; supply it at most once. limit is 1–100, default 20. Results are ordered by name using case-sensitive binary order, not locale-specific collation. Continue with cursor and the same inbox and prefix.
Counts describe messages, not conversations, and include all processing and sending states. A name disappears when no undeleted message uses it. There is no separate label registry or rename operation. Results and counts can change while you paginate.
Parameters
| Parameter | Location | Required | Type | Meaning |
|---|---|---|---|---|
inbox_id | path | Yes | string | Owned Cherami resource ID returned by the API. |
limit | query | No | integer | Decimal integer without signs, whitespace or leading zeroes. minimum: 1 maximum: 100 default: 20 |
cursor | query | No | string | Opaque returned cursor. Keep resource URL, filters and ordering unchanged; stop when next_cursor is null. |
prefix | query | No | string | Literal case-sensitive prefix, trimmed, at most 128 UTF-8 bytes. Empty means all labels. Supply at most once. |
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/INBOX_ID/labels" \
--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.
{
"labels": [],
"next_cursor": null
}HTTP 400
invalid_limit: Use an integer from 1 to 100.
invalid_cursor: Use the cursor with its original resource and filters, or restart from the first page. Draft listings instead report invalid_draft.
invalid_labels: Correct label names, changes, filter groups, or discovery prefix.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
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: LabelList
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
labels | Yes | array of object | |
next_cursor | Yes | string or null |
labels fields
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
name | Yes | string | |
received_count | Yes | integer | minimum: 0 |
sent_count | Yes | integer | minimum: 0 |
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