Label a received message
PATCH /v1/messages/{message_id}
Read as Markdown ↗PATCH /v1/messages/{message_id}
Requires an API key: Authorization: Bearer YOUR_CREDENTIAL.
Adds and removes labels on one received message, leaving its other labels as they are. Names are case-sensitive: Receipts and receipts are different labels. The response lists the message's labels after the change, and repeating a change is harmless.
To track read and starred mail with labels, see Track read, unread and starred mail.
Parameters
| Parameter | Location | Required | Type | Meaning |
|---|---|---|---|---|
message_id | path | Yes | string | Cherami resource ID returned by the API. |
Request body
JSON object, at most 20 KiB in total.
Schema: LabelChange
At least one array must contain a label, and a name can't be in both.
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
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.
{
"add_labels": [
"handled"
],
"remove_labels": [
"needs-review"
]
}curl --silent --show-error --include --request PATCH \
"https://cherami.to/v1/messages/MESSAGE_ID" \
--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.
{
"id": "11111111-1111-4111-8111-111111111111",
"labels": []
}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.
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