cherami.
API referenceLabels

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

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

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

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

Responses

HTTP 200

Success.

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

Content type: application/json.

LabelResult

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

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