Official scripts
Explore our curated collection of scripts
Get Current Gmail User
Return the display name and email of the Gmail account this browser is signed in as.
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).
List Gmail inbox
List the messages on the first page of the Gmail inbox. Requires an authenticated mail.google.com session. Returns folder, total (the range line as rendered, e.g. "1–50 of 240") and rows of sender, subject, snippet, date plus the unread / starred / hasAttachment flags. Covers only the first inbox page (up to ~50 rows as Gmail renders it); there is no pagination. An empty inbox returns an empty rows list. Pass account to list another signed-in account's inbox.
Download Gmail attachments
Download every attachment of a Gmail thread, given its thread id as returned by search_emails, and save the files to your computer under their real names. Returns the thread id, how many files were saved, and each file's name and path. Attachments from every message in the thread are included, and inline images count as attachments.
Send Gmail email
Send an email from the signed-in Gmail account, with a plain-text body and an optional single file attachment. Always starts a new conversation. To answer inside an existing thread, use mail.google.com/reply_to_email.
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.
List Gmail labels / folders
List the Gmail labels and system folders visible to the account, with their unread counts where Gmail shows one. Distinguishes system folders (Inbox, Sent, Drafts, Spam, Bin...) from user-created labels.
List Google accounts signed in on this browser (Gmail)
List the Google accounts signed in on this browser, as the Gmail account switcher shows them. Each account comes back with its address, the index that addresses it in a Google URL, and whether it is the one Gmail opens by default. The index is what the other Gmail scripts take as their account argument, so this answers which account a script acts as when none is given.
Archive Gmail thread
Archive a Gmail thread by its hex threadId: it leaves the Inbox and stays in All Mail. Returns archived and threadId, plus already_archived:true when the thread was not in the Inbox (nothing was changed). Fails with an error, rather than reporting success, when the thread cannot be found or Gmail does not confirm it left the Inbox.
Trash Gmail thread
Move a Gmail thread to the Bin by its hex threadId. Returns trashed and threadId only once the thread is confirmed in the Bin; otherwise it fails with an error naming what happened, and nothing else is deleted.
Reply to Gmail thread
Reply (or reply-all) inside an existing Gmail conversation, given its thread id or the conversation's link, so the reply stays in the same thread with the original subject and quoted history. Optionally add Cc recipients, attach one file, or schedule the reply for later. Returns whether it was sent or scheduled, the conversation id and subject, and for scheduled replies the time Gmail shows. To start a new conversation instead, use mail.google.com/send_email.
Gmail whoami (signed-in account)
Report which Gmail account this browser is signed in as: display name and email, from Gmail's account switcher. When the browser is signed out, the run fails with a signed-out error that asks to sign in to Gmail, so it can be used to check a session before running other Gmail scripts.
Mark Gmail thread as read
Mark a Gmail thread as read by its hex threadId, in the chosen Google account, wherever the thread is filed. Returns read, threadId and already_read. Safe to repeat: a thread that is already read returns already_read:true without changing anything. Success is reported only once Gmail has saved the change and a fresh read shows the thread read. An unknown or malformed id is refused without changing anything.
Mark Gmail thread as unread
Mark a Gmail thread as unread by its hex threadId, in the chosen Google account, wherever the thread is filed. Returns unread, threadId and already_unread. Safe to repeat: a thread that is already unread returns already_unread:true without changing anything. Success is reported only once Gmail has saved the change and a fresh read shows the thread unread. An unknown or malformed id is refused without changing anything.
Report Gmail thread as spam
Report a Gmail thread as spam by its hex threadId, as returned by search_emails, so it moves to the Spam folder. Returns reportedSpam and threadId only once the thread is confirmed in Spam. A thread already in Spam or in the Bin, or an id Gmail cannot open, is refused with nothing changed. Reporting also teaches Gmail's spam filter about that sender, which moving the thread back does not fully undo. Pass account when several Google accounts share the browser. For senders with an unsubscribe link Gmail asks whether to report or unsubscribe; the script never answers that question for you: it closes it and fails with nothing reported, so such mail must be reported by hand.
Create a Gmail draft
Compose a Gmail message and save it as a draft without sending it. Takes to/cc/bcc, a subject and a plain-text body, and can put one of the account's Gmail signatures under the body by its name, or none; without that choice the draft keeps Gmail's default signature for new emails. Reports success only once Gmail confirms the draft is saved under Drafts with that subject and body, and returns the account used, the draft id that update_draft and send_draft take, and the id of its conversation. Create drafts one after another on a browser: several at once can leave Gmail without saving some of them, which the call reports as an error.
Forward Gmail thread
Forward an entire Gmail thread to one recipient, with an optional note placed above the forwarded content. Takes the hex threadId that search_emails returns and forwards the whole conversation inline rather than a single message. Returns forwarded, threadId and to once Gmail has accepted the send. A thread id Gmail cannot open is refused with nothing sent, and so is a conversation that still has a scheduled reply pending (Gmail hides its Forward control then). Forwarding a conversation that sits in the Bin works, but Gmail then keeps the sent copy out of the Sent folder.
Save a place to a Google Maps list
Save one Google Maps place to one of your saved lists, such as Favorites, Want to go or a list you made. Give the place by its place id (from search_places or get_place) or by a query that names one place, and the list by its name. When several Google accounts are signed in on the browser, choose one by its index from mail.google.com/list_accounts; the default is the browser's first account. Returns the place's name, the email of the account it was saved for, and whether it was saved now or was already in that list, so running it twice changes nothing. A query that Maps answers with a list of places fails and asks for search_places. A list name the account does not have fails and names the lists it has. Undo it with unsave_place.
Send a Gmail draft
Send an existing Gmail draft, identified by the id the drafts listing gives you: a new message, or a reply saved inside a conversation. This delivers a real message and cannot be undone. The draft's recipients and subject are reported back with the send, and a draft with no recipient is refused rather than attempted. The call succeeds only once Gmail confirms the send; otherwise it fails and says whether anything may have gone out. The conversation id is returned and is the same before and after sending, so the message can be found again afterwards. Sending a reply opens its conversation, which marks it as read.
List Gmail drafts
List the unsent drafts in the signed-in Gmail account, each with the identifier needed to open, edit or send it, plus its subject, preview text, whether it carries an attachment, and the date Gmail shows. Replies saved inside an existing conversation are listed alongside new messages. Gmail's own draft total is returned alongside the number of drafts read, so a mailbox with more drafts than one screenful is visible as such rather than looking complete. An account with no drafts is a normal empty result, not an error. The drafts list does not show who a draft is addressed to, since Gmail puts the word "Draft" where the recipient would be, so recipients have to come from opening the draft itself.
Unsubscribe from a sender in Gmail
Unsubscribe from a mailing list using Gmail's own unsubscribe control, which appears beside the sender on a message carrying a List-Unsubscribe header, in the chosen Google account. Returns the sender it acted on, whether the control was present, and whether Gmail confirmed the request. This leaves the mailing list for real and cannot be undone from Gmail: confirm the exact sender with the user before running, and note that approval for one sender does not carry over to another. The sender is checked against the one expected before anything is clicked. Senders with no unsubscribe control are reported rather than acted on, and the script never falls back to reporting spam. The run fails, doing nothing, if the requested account is not signed in.
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.
Remove a place from a Google Maps list
Remove one Google Maps place from one of your saved lists, such as Favorites, Want to go or a list you made. Give the place by its place id (from search_places or get_place) or by a query that names one place, and the list by its name. When several Google accounts are signed in on the browser, choose one by its index from mail.google.com/list_accounts; the default is the browser's first account. Returns the place's name, the email of the account it was removed for, and whether it was removed now or was not in that list, so running it twice changes nothing. The place stays in the account's other lists. A query that Maps answers with a list of places fails and asks for search_places. A list name the account does not have fails and names the lists it has. This undoes save_place.
Toggle Gmail thread read state
Mark a Gmail thread as read or unread by its hex threadId, in the chosen Google account. Pass read:true to mark as read (default), read:false to mark as unread. Returns the final read and unread state, threadId, and already_read/already_unread when the thread was already in the requested state and was left alone, so repeating the call is safe. Success is reported only once Gmail has saved the change and a fresh read confirms it. An unknown or malformed id is refused without changing anything.
Update a Gmail draft
Change the subject and/or body of an existing Gmail draft, identified by the id the drafts listing gives you. Whichever field you leave out keeps its current value; a field you pass replaces what was there rather than appending to it. The draft's current contents are read first, so asking for what it already says makes no change and says so. Gmail issues a draft a new id every time it is saved, so the id you passed in stops existing and the new one is returned — use that for any follow-up. The conversation id stays the same and is returned as the stable handle. Recipients are not touched by this script.