Label several sent copies

PATCH /v1/sent/labels

Requires a Claim-issued API key: Authorization: Bearer YOUR_CREDENTIAL.

Changes labels on an explicit set of saved outgoing copies. The individual label rules 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 bodyCopy Anchor Link

JSON object. Total UTF-8 request body limit: 32768 bytes.

Schema: BulkLabelChangeCopy Anchor Link

At least one nonempty change array; additions and removals must not overlap. Duplicate IDs are updated once.

Unknown fields are rejected.

curl exampleCopy Anchor Link

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.

{
  "message_ids": [
    "22222222-2222-4222-8222-222222222222"
  ],
  "add_labels": [
    "handled"
  ]
}

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

ResponsesCopy Anchor Link

HTTP 200Copy Anchor Link

Successful operation; inspect resource state and outcome fields.

• X-Request-ID: Support correlation ID, not an idempotency key.

Content type: application/json.

{
  "messages": []
}

HTTP 400Copy Anchor Link

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

HTTP 401Copy Anchor Link

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.

Error

HTTP 404Copy Anchor Link

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

HTTP 413Copy Anchor Link

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

HTTP 415Copy Anchor Link

unsupported_media_type: Send Content-Type: application/json.

• X-Request-ID: Support correlation ID, not an idempotency key.

Content type: application/json.

Error

HTTP 500Copy Anchor Link

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: LabelResultCopy Anchor Link

Schema: ErrorCopy Anchor Link

error fieldsCopy Anchor Link

Schema: LabelCopy Anchor Link

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