Summary
Add or remove the same labels on 1 to 50 messages. Body is message_ids plus add_labels and/or remove_labels. At least one label list must be non-empty (400 missing_labels). An empty message_ids array is 400 missing_message_ids. Duplicate ids are 400 duplicate_message_ids. More than 50 ids are 400 too_many_ids. read and unread can change. Other system labels return protected_label, invalid_label, or label_conflict, the same as PATCH on one message. Ids that are not in this inbox are omitted. The messages that are in this inbox all update, or none do. Returns {object:"list", limit, count, data} with full message JSON in request order. limit is the number of ids in the request. count is how many updated. Works on a paused inbox. A held message keeps the held label and a withheld body. An inbox-scoped key for another inbox is 404 inbox_not_found. MCP: cooper_update_messages.
Request
{
"message_ids": [
"msg_a",
"msg_b"
],
"remove_labels": [
"unread"
],
"add_labels": [
"read"
]
}Response
HTTP 200. Sample values illustrate the schema.
{
"object": "list",
"limit": 1,
"count": 1,
"data": [
{
"id": "inb_example",
"inbox_id": "inb_example",
"thread_id": "thr_example",
"direction": "inbound",
"from": "ada@example.com",
"to": [
"string"
],
"subject": "Hello",
"text": "Tuesday works.",
"html": "string",
"extracted_text": "string",
"extracted_html": "string",
"preview": "string",
"delivery_events": [
{
"type": "string",
"recipient": "string",
"created_at": "2026-10-18T12:00:00.000Z",
"detail": "string"
}
],
"cc": [
"string"
],
"bcc": [
"string"
],
"reply_to": "string",
"in_reply_to": "string",
"references": [
"string"
],
"labels": [
"string"
],
"auth": {
"spf": "string",
"dkim": "string",
"dmarc": "string"
}
}
]
}Errors
- HTTP 400 missing_labels
- HTTP 400 missing_message_ids
- HTTP 400 duplicate_message_ids
- HTTP 400 too_many_ids
- HTTP 404 inbox_not_found
Idempotency
This route does not document Idempotency-Key or client_id.