Labels

Labels are short strings on messages. A thread’s labels are the union of its messages’ labels.

System labels

Label	Set by	Agents may change
received	simail, on inbound mail	no
sent	simail, on outbound mail	no
unread	simail, on inbound mail	yes
important	you	yes
draft	simail	no
held	simail; cleared when a human releases the message	no
spam	simail	no
blocked	simail (sender on a block list)	no
trash	DELETE on a message or thread	no (only by deleting)

Custom labels

Any other lowercase string up to 64 characters (a-z, 0-9, -, _, ., /) is a custom label, for example orders or needs-human. Agents may add and remove custom labels freely.

Changing labels

PATCH/v0/inboxes/{inbox_id}/messages/{message_id}

PATCH/v0/inboxes/{inbox_id}/threads/{thread_id}

POST/v0/inboxes/{inbox_id}/messages/batch-update

All need message_update and take:

{ "add_labels": ["orders"], "remove_labels": ["unread"] }

Trying to change a label agents may not change returns 400 validation_error. Changes publish label.added and label.removed. Sends can set labels on the sent copy with labels.

Filtering

List and search endpoints take labels=a,b (all must match). spam, blocked and trash are left out of listings unless you pass include_spam, include_blocked or include_trash, each of which needs its label_*_read permission.

MCP: list_labels and update_labels.