Label several received messages
PATCH /v1/messages/labels
Read as Markdown ↗PATCH /v1/messages/labels
Requires an API key: Authorization: Bearer YOUR_CREDENTIAL.
Applies one label change to up to 100 received messages, which may be in any of the account's inboxes. The label rules apply; sent copies have their own endpoint.
The change is all or nothing: if any ID is missing, deleted or not on this account, the request returns 404 and no message changes. On success the response has one entry per distinct ID, in request order. For more than 100 messages, send several requests.
Request body
JSON object, at most 32 KiB in total.
Schema: BulkLabelChange
At least one nonempty change array, and no name in both. Duplicate IDs are updated once.
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
message_ids | Yes | array of string | minItems: 1 maxItems: 100 |
add_labels | No | array of Label | Label names, case-sensitive; order and duplicates don't matter. maxItems: 32 |
remove_labels | No | array of Label | Label names, case-sensitive; order and duplicates don't matter. maxItems: 32 |
Unknown fields are rejected.
curl example
Supply CHERAMI_API_KEY privately.
Save the payload as request.json, replacing the example values.
{
"message_ids": [
"22222222-2222-4222-8222-222222222222"
],
"add_labels": [
"handled"
]
}curl --silent --show-error --include --request PATCH \
"https://cherami.to/v1/messages/labels" \
--header "Authorization: Bearer $CHERAMI_API_KEY" \
--header 'Content-Type: application/json' \
--data-binary @request.jsonResponses
HTTP 200
Success.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
messages | Yes | array of LabelResult |
{
"messages": []
}HTTP 400
invalid_json: Send a valid UTF-8 JSON object, not an array or scalar.
invalid_labels: Correct the label name, label change, filter group or discovery prefix the message names.
invalid_message_ids: Supply 1–100 valid message IDs for a bulk label update.
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 413
body_too_large: Reduce the JSON request to the operation's body limit.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
HTTP 415
unsupported_media_type: Send Content-Type: application/json.
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: LabelResult
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
id | Yes | string | Cherami resource ID. |
labels | Yes | array of string |
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. |
Schema: Label
1–128 UTF-8 bytes after trimming, without control characters; case-sensitive.
string. x-max-utf8-bytes: 128