UpdateThreadLabelsCopy Anchor Link

Add or remove a single label from every message in a Gmail thread. In Gmail, nearly all inbox operations are just label add/remove operations, so this tool is the primitive for archiving, marking read/unread, starring, trashing, marking important/spam, and applying or removing custom labels.

Name the label with exactly one of label or label_id. label is a system label (INBOX, UNREAD, STARRED, IMPORTANT, TRASH, SPAM) or a custom label's display name, matched in the thread's own inbox, so it works across inboxes without a lookup. label_id is a UUID from ListLabels. Pass add=true to apply or add=false to remove. Each call modifies one label — to do multiple changes on the same thread (e.g. archive AND mark read), call this tool once per label.

Common operations:

• Archive: remove INBOX (add=false)
• Move back to inbox: add INBOX (add=true)
• Mark as read: remove UNREAD (add=false)
• Mark as unread: add UNREAD (add=true)
• Star: add STARRED (add=true) / Unstar: remove (add=false)
• Move to trash: add TRASH (add=true) / Restore: remove (add=false)
• Mark important: add IMPORTANT (add=true) / Mark unimportant: remove (add=false)
• Report spam: add SPAM (add=true) / Not spam: remove (add=false)
• Apply custom user label: add the label with that display name (add=true) / Remove: (add=false)

In an Outlook inbox the same system label names set the matching mailbox state (archive, read, flag, trash, junk); IMPORTANT has no Outlook equivalent, and other names are Outlook categories.

thread_id is the email thread UUID (the same id returned by ListEntities, search results, or GetThread). label_id is the UUID returned by ListLabels — NOT the label name; pass a name in label instead.

ParametersCopy Anchor Link