App Logo
mail.google.com

Gmail — Apply or remove a label on a thread

Apply a label to a Gmail thread by its hex threadId, optionally creating the label first, or take the label off again with remove:true. A thread already in the requested state is reported as a no-op without clicking. Takes a received thread — Gmail renders no conversation heading for a thread you sent to yourself, so those are refused rather than risk labelling the wrong thread.

Input

label required

The label name, matched exactly against the account's labels. Exactness matters, because Gmail's own picker offers to create "Lunch" even when "Lunch Bill" exists, so a partial name would quietly make a second label. Gmail's category names (Social, Updates, Forums, Promotions) appear in the same menu but are not user labels.

threadId required

The thread's hex id, as returned by mail.google.com/search_emails (its threadId field, Gmail's data-legacy-thread-id). Note that list_inbox does not return thread ids. Must be a received thread: Gmail does not render a conversation heading for a thread you sent to yourself, and those are refused rather than risk labelling the wrong thread.

create optional

Allow creating the label when the account does not have it. Default false, so a typo fails loudly instead of quietly making a new label. Ignored when remove is true.

Default: false
remove optional

Leave false (the default) to apply the label. Set true to take it off.

Default: false
account optional

Optional authuser value for a browser signed into several Google accounts. Omit for the default (u/0).

Output

label required
applied required

Whether the thread carries the label after this run, read from a Gmail label search rather than the label menu, which does not report applied state in conversation view.

threadId required
already_present required

True when the thread was already in the requested state, so nothing was written.

created optional
attempts optional

How many click attempts the toggle needed before Gmail's own label search agreed. More than 1 means a click silently failed to reach the server and was retried.

accountUsed optional
verified_by optional

'search' when the outcome was confirmed against Gmail's own label search; 'unconfirmed' when the label holds more threads than the first search page, so absence could not be told apart from paging.

availableLabels optional
sync_acknowledged optional

Whether Gmail's own sync write was observed for this toggle.

FAQ

Apply a label to a Gmail thread by its hex threadId, optionally creating the label first, or take the label off again with remove:true. A thread already in the requested state is reported as a no-op without clicking. Takes a received thread — Gmail renders no conversation heading for a thread you sent to yourself, so those are refused rather than risk labelling the wrong thread.
Required: threadId, label. Optional: create, remove, account.
It returns label, applied, created, attempts, threadId, accountUsed, verified_by, already_present, availableLabels, sync_acknowledged.
Yes. It acts as you on mail.google.com: on your own Chrome it reuses your session, and on a Reduck-hosted browser it loads the mail.google.com cookies saved by the Reduck extension.
It makes changes on mail.google.com, like sending, posting or booking something.
Ask an AI agent connected to Reduck to run reduck/mail.google.com/add_label, or run it from a terminal with the Reduck CLI: npx @reduck-ai/cli@latest run --script reduck/mail.google.com/add_label
It is part of Reduck's official curated catalogue.

Related scripts

mail.google.com

Search Gmail

Search the signed-in Gmail with the native query syntax (from:, to:, subject:, has:attachment, after:/before:, labels…) and return matching threads: threadId (feed it to get_thread / reply_to_email), sender, senderEmail, subject, snippet, date, unread, starred, hasAttachment. Results are threads rather than individual messages, which is Gmail's own search granularity, and only the first page of results is returned (up to 50).

mail.google.com

Send Gmail email

Send an email from the signed-in Gmail account, with a plain-text body and an optional single file attachment.

mail.google.com

Forward Gmail thread

Forward an entire Gmail thread to one recipient, with an optional leading note. Takes the hex threadId that search_emails returns, and forwards the whole conversation inline rather than a single message. Returns forwarded, threadId and to. The thread must be on the first page of All Mail, newest-first, so older conversations cannot be reached this way.

Start building not clicking

Get started for free