Labels API

Labels are the agent's own notes on received mail. They don't affect the policy, risk checks, or approvals. Both paths need the Read (messages:read) scope. Quarantined mail can't be labeled and isn't counted.

Set labels on an email#

PUT /v1/messages/inbound/{messageId}/labels

Send one of the two forms.

{ "labels": ["invoice", "needs-reply"] }

{ "add": ["done"], "remove": ["needs-reply"] }

The response is the email's labels after the change.

{ "message_id": "e4b2…77d0", "labels": ["done", "invoice"] }

• A label is 1–64 characters: lowercase letters, digits, ., _, or -, starting with a letter or digit.
• An email can have up to 20 labels. An agent can use up to 200 different labels.
• Unknown or quarantined mail gives 404 message_not_found.

List labels#

GET /v1/labels?agent_id={agentId}

{
  "agent_id": "7c21…f5a1",
  "labels": [
    { "label": "invoice", "count": 12, "unread": 3 },
    { "label": "needs-reply", "count": 4, "unread": 4 }
  ],
  "limits": { "per_message": 20, "per_agent": 200 }
}

count is how many visible emails have the label, and unread is how many of those haven't been opened yet.

Filter the inbox#

GET /v1/messages/inbound takes three more filters. Each email in the list also has labels and read.

An email counts as read the first time it's opened with GET /v1/messages/inbound/{messageId} or the MCP read_email tool. Listing doesn't mark it read.

Errors#