cherami.
API referenceLabels

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

ParameterLocationRequiredTypeMeaning
inbox_idpathYesstringCherami resource ID returned by the API.
limitqueryNointegerResults per page. minimum: 1 maximum: 100 default: 20
cursorqueryNostringnext_cursor from the previous page. Keep the URL, filters and order unchanged.
prefixqueryNostringOnly 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.

LabelList

{
  "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.

Error

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.

Error

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.

Error

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.

Error

Schema: LabelList

FieldRequiredTypeMeaning and constraints
labelsYesarray of object
next_cursorYesstring or null

labels fields

FieldRequiredTypeMeaning and constraints
nameYesstring
received_countYesintegerminimum: 0
sent_countYesintegerminimum: 0

Schema: Error

FieldRequiredTypeMeaning and constraints
errorYesobject

error fields

FieldRequiredTypeMeaning and constraints
codeYesstringCode to handle. Handle a code you don't recognize by its HTTP status.
messageYesstringExplanation of this case; its wording can change.

Errors, limits and pagination · Download OpenAPI 3.1

On this page