cherami.
API referenceLabels

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.

FieldRequiredTypeMeaning and constraints
message_idsYesarray of stringminItems: 1 maxItems: 100
add_labelsNoarray of LabelLabel names, case-sensitive; order and duplicates don't matter. maxItems: 32
remove_labelsNoarray of LabelLabel 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.json

Responses

HTTP 200

Success.

  • X-Request-ID: Identifies this request; include it when reporting a problem.

Content type: application/json.

FieldRequiredTypeMeaning and constraints
messagesYesarray 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.

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

Error

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.

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: LabelResult

FieldRequiredTypeMeaning and constraints
idYesstringCherami resource ID.
labelsYesarray of string

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.

Schema: Label

1–128 UTF-8 bytes after trimming, without control characters; case-sensitive.

string. x-max-utf8-bytes: 128

Errors, limits and pagination · Download OpenAPI 3.1

On this page