App Logo
mail.google.com

Gmail — Apply or remove a label on a thread

Automatically apply or remove a label on a thread on mail.google.com. 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 id, from the threadId field of mail.google.com/search_emails (list_inbox does not return thread ids). Must be a thread you received; threads you sent only to yourself are refused.

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.
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
You do not need one. "Gmail — Apply or remove a label on a thread" drives the real mail.google.com pages in a browser, so it works whether or not mail.google.com offers an API for this.
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, booking or buying 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

Get Gmail thread

Read a Gmail thread by its hex threadId (as returned by search_emails): subject plus every rendered message's from, fromEmail, to, date, plain-text body and attachment names. In long threads Gmail collapses older messages, so only rendered (expanded) messages are returned.

Start building not clicking

Get started for free