Discover labels
GET /v1/inboxes/{inbox_id}/labels
Read as Markdown ↗GET /v1/inboxes/{inbox_id}/labels
Requires an API key: Authorization: Bearer YOUR_CREDENTIAL.
Lists the label names in use on the inbox's received and sent mail, with how many messages carry each in received_count and sent_count. prefix narrows the list to names starting with it, case-sensitive.
A name disappears once no message carries it. There is no separate step to create, rename or delete a label: add or remove it on messages.
Parameters
| Parameter | Location | Required | Type | Meaning |
|---|---|---|---|---|
inbox_id | path | Yes | string | Cherami resource ID returned by the API. |
limit | query | No | integer | Results per page. minimum: 1 maximum: 100 default: 20 |
cursor | query | No | string | next_cursor from the previous page. Keep the URL, filters and order unchanged. |
prefix | query | No | string | Only names starting with this text, case-sensitive; empty means all. At most 128 UTF-8 bytes, supplied once. |
curl example
Supply CHERAMI_API_KEY privately.
curl --silent --show-error --include --request GET \
"https://cherami.to/v1/inboxes/INBOX_ID/labels" \
--header "Authorization: Bearer $CHERAMI_API_KEY"Responses
HTTP 200
Success.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
{
"labels": [],
"next_cursor": null
}HTTP 400
invalid_limit: Use an integer from 1 to 100.
invalid_cursor: Send a cursor only to the listing, filters and order that returned it, or restart from the first page.
invalid_labels: Correct the label name, label change, filter group or discovery prefix the message names.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
HTTP 401
unauthorized: Send a valid API key as Authorization: Bearer <key>. If the key stopped working, get a new one through recovery.
X-Request-ID: Identifies this request; include it when reporting a problem.WWW-Authenticate:"Bearer"
Content type: application/json.
HTTP 404
not_found: The resource does not exist or does not belong to this account. A reply or forward source must also be in the sending inbox.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
HTTP 500
internal_error: The operation failed. Retry a read; after a write the change may have happened, so recover as retry by operation describes.
X-Request-ID: Identifies this request; include it when reporting a problem.
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 | Code to handle. Handle a code you don't recognize by its HTTP status. |
message | Yes | string | Explanation of this case; its wording can change. |