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. Both are the same checkbox in Gmail's own "Label as" menu, so they are one flag rather than two scripts. A thread already in the requested state is reported as a no-op without clicking. The result is confirmed against Gmail's own label search, not the label menu: in conversation view nothing is selected, so every menu row reads as unchecked whatever the thread actually carries, and this build renders no label chips either. Takes a received thread — Gmail renders no conversation heading for a thread you sent to yourself, and 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
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.

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

Create a Gmail draft

Compose a Gmail message and save it as a draft without sending it. Takes to/cc/bcc, subject and body, and confirms the draft exists in Drafts afterward rather than trusting the compose window closing.

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.

Start building not clicking

Get started for free