Label a sent copy
PATCH /v1/sent/{message_id}
Read as Markdown ↗PATCH /v1/sent/{message_id}
Requires a Claim-issued API key: Authorization: Bearer YOUR_CREDENTIAL.
Adds or removes labels on a saved outgoing message. The individual label validation rules apply: a JSON body up to 20 KiB, at least one nonempty change array, and no name in both arrays after trimming. Labels are case-sensitive sets; duplicate names within an array are ignored.
Returns 200 with the message ID and resulting labels. Additions and removals apply together without replacing unrelated labels. Repeating a change does not duplicate tags. Concurrent changes to different labels survive; opposite changes to the same label follow write order. Labels do not claim work for one agent.
Invalid changes return 400 invalid_labels. Missing, deleted or other-account messages return 404. Updating labels requires neither sending nor deletion permission and consumes no sending allowance.
Parameters
| Parameter | Location | Required | Type | Meaning |
|---|---|---|---|---|
message_id | path | Yes | string | Owned Cherami resource ID returned by the API. |
Request body
JSON object. Total UTF-8 request body limit: 20480 bytes.
Schema: LabelChange
At least one array must contain a label. A normalized label cannot occur in both arrays.
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
add_labels | No | array of Label | Trimmed, deduplicated and case-sensitive. Order is not significant. maxItems: 32 |
remove_labels | No | array of Label | Trimmed, deduplicated and case-sensitive. Order is not significant. maxItems: 32 |
Unknown fields are rejected.
curl example
Replace resource-ID placeholders with returned IDs. Supply CHERAMI_API_KEY through your private shell environment.
Save the intended payload as a private request.json file and replace illustrative values. For an uncertain response, follow the operation-specific recovery rules.
{
"add_labels": [
"handled"
],
"remove_labels": [
"needs-review"
]
}curl --silent --show-error --include --request PATCH \
"https://cherami.to/v1/sent/MESSAGE_ID" \
--header "Authorization: Bearer $CHERAMI_API_KEY" \
--header 'Content-Type: application/json' \
--data-binary @request.jsonResponses
HTTP 200
Successful operation; inspect resource state and outcome fields.
X-Request-ID: Support correlation ID, not an idempotency key.
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 label names, changes, filter groups, or discovery prefix.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
HTTP 401
unauthorized: Provide a valid bearer credential. Use human-approved recovery if access is lost.
X-Request-ID: Support correlation ID, not an idempotency key.WWW-Authenticate:"Bearer"
Content type: application/json.
HTTP 404
not_found: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
HTTP 413
body_too_large: Reduce the JSON request to the endpoint's body limit.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
HTTP 415
unsupported_media_type: Send Content-Type: application/json.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
HTTP 500
internal_error: Operation failed; a write may already have happened. Follow the operation-specific recovery below.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
Schema: LabelResult
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
id | Yes | string | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value. |
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 | Programmatic error code. Handle unrecognized codes by status and operation-specific recovery. |
message | Yes | string | Human-readable context, not a stable string to match. |
Schema: Label
1–128 UTF-8 bytes after trimming. Well-formed Unicode without control characters; case-sensitive.
string. x-max-utf8-bytes: 128
HTTP conventions, errors and pagination · Download OpenAPI 3.1