# Label several sent copies PATCH /v1/sent/labels Source: https://cherami.to/docs/api/labels/bulk-update-sent-labels {/* Generated from apps/web/openapi. Edit the contract, not this file. */} `PATCH /v1/sent/labels` Requires a [Claim-issued API key](https://cherami.to/docs/api#authentication): `Authorization: Bearer YOUR_CREDENTIAL`. Changes labels on an explicit set of saved outgoing copies. The [individual label rules](https://cherami.to/docs/api/labels/update-message-labels) apply; the body may contain up to 32 KiB of JSON. Supply 1โ€“100 message IDs in `message_ids`; duplicate IDs are updated once. Only `message_ids`, `add_labels`, and `remove_labels` are accepted. The same additions and removals apply to every target. IDs can belong to different inboxes owned by the account, but received and sent copies must use their respective endpoint. The request is atomic: if any target is missing, deleted, or inaccessible, the response is a generic `404` and no labels change. Invalid ID arrays return `400 invalid_message_ids`. Success returns `200` with one result per distinct ID in request order. Select explicit IDs before updating; this endpoint does not accept a filter. Larger jobs require separate batches, each atomic on its own. If a response is lost, the whole batch may have applied. Inspect current labels before retrying when other agents may be changing the same tags. ## Request body [#request-body] JSON object. Total UTF-8 request body limit: 32768 bytes. ### Schema: BulkLabelChange [#schema-bulklabelchange] At least one nonempty change array; additions and removals must not overlap. 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](#schema-label) | Trimmed, deduplicated and case-sensitive. Order is not significant. `maxItems`: `32` | | `remove_labels` | No | array of [Label](#schema-label) | Trimmed, deduplicated and case-sensitive. Order is not significant. `maxItems`: `32` | Unknown fields are rejected. ## curl example [#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](https://cherami.to/docs/api/errors#retry-by-operation). ```json { "message_ids": [ "22222222-2222-4222-8222-222222222222" ], "add_labels": [ "handled" ] } ``` ```sh curl --silent --show-error --include --request PATCH \ "https://cherami.to/v1/sent/labels" \ --header "Authorization: Bearer $CHERAMI_API_KEY" \ --header 'Content-Type: application/json' \ --data-binary @request.json ``` ## Responses [#responses] ### HTTP 200 [#http-200] Successful operation; inspect resource state and outcome fields. * `X-Request-ID`: Support correlation ID, not an idempotency key. Content type: `application/json`. | Field | Required | Type | Meaning and constraints | | ---------- | -------- | ------------------------------------------- | ----------------------- | | `messages` | Yes | array of [LabelResult](#schema-labelresult) | | ```json { "messages": [] } ``` ### HTTP 400 [#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. `invalid_message_ids`: Supply 1โ€“100 valid message IDs for a bulk label update. * `X-Request-ID`: Support correlation ID, not an idempotency key. Content type: `application/json`. [Error](#schema-error) ### HTTP 401 [#http-401] `unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost. * `X-Request-ID`: Support correlation ID, not an idempotency key. * `WWW-Authenticate`: `"Bearer"` Content type: `application/json`. [Error](#schema-error) ### HTTP 404 [#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`. [Error](#schema-error) ### HTTP 413 [#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`. [Error](#schema-error) ### HTTP 415 [#http-415] `unsupported_media_type`: Send `Content-Type: application/json`. * `X-Request-ID`: Support correlation ID, not an idempotency key. Content type: `application/json`. [Error](#schema-error) ### HTTP 500 [#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`. [Error](#schema-error) ## Schema: LabelResult [#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 [#schema-error] | Field | Required | Type | Meaning and constraints | | ------- | -------- | ------ | ----------------------- | | `error` | Yes | object | | ### `error` fields [#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 [#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](https://cherami.to/docs/api/errors) ยท [Download OpenAPI 3.1](https://cherami.to/openapi.json)