Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

2.5 KB
Raw Blame
---
title: UpdateThreadLabels
description: >-
  Add or remove a single label from every message in a Gmail thread.
---

# UpdateThreadLabels

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.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `thread_id` | string | Yes | The ID of the email thread to modify. Same UUID returned by ListEntities, search, or GetThread. |
| `label_id` | string | No | The UUID of the label to add or remove, from ListLabels. Omit when passing `label`. |
| `label` | string | No | The label's name instead of its id: a system label (INBOX, UNREAD, STARRED, IMPORTANT, TRASH, SPAM) or a custom label's display name, matched in the thread's inbox. Omit when passing `label_id`. |
| `add` | boolean | Yes | Whether to add (true) or remove (false) the label from every message in the thread. |