mail.update_thread_labels

Scope: mail:manage

Add or remove labels on a thread. Thread labels are separate from message labels — use them for user-applied tags like starred, important, archived, or any custom label. Message-level labels (sent, received, unread, spam) are managed via mail.update_labels.

Parameters

Name	Type	Required	Description
`threadId`	`string`	Yes	Thread ID
`addLabels`	`string[]`	No	Labels to add (e.g. `'starred'`, `'follow-up'`)
`removeLabels`	`string[]`	No	Labels to remove

At least one of addLabels or removeLabels must be provided.

Example

Agent: "Star the pricing thread and mark it as follow-up"

-> mail.update_thread_labels({
    threadId: "thd_a3f91b00c4e2d7e8",
    addLabels: ["starred", "follow-up"]
  })

Returns

{
  "threadId": "thd_a3f91b00c4e2d7e8",
  "inboxId": "agent-x8k2m@mailgent.dev",
  "subject": "Question about pricing",
  "labels": ["starred", "follow-up"],
  "createdAt": "2026-03-28T10:00:00.000Z",
  "updatedAt": "2026-04-06T14:00:00.000Z"
}

Common Patterns

Intent	Call
Star a thread	`addLabels: ["starred"]`
Unstar	`removeLabels: ["starred"]`
Mark important	`addLabels: ["important"]`
Archive	`addLabels: ["archived"]`
Custom tag	`addLabels: ["customer-feedback"]`
Replace	`addLabels: ["archived"], removeLabels: ["inbox"]`

Thread vs Message Labels

Label type	Scope	Tool	Examples
Thread labels	Whole conversation	`mail.update_thread_labels`	starred, important, archived, custom
Message labels	Single message	`mail.update_labels`	unread, sent, received, spam, read

Thread labels persist across replies and apply to the entire conversation. Message labels describe the state of a single message (e.g. whether the agent has read it).

REST Equivalent

PATCH /v0/threads/:threadId