App Logo
mail.google.com

Search Gmail

TL;DR

Automatically search Gmail on mail.google.com. Takes any Gmail search query and returns up to 50 matching threads as JSON, each with a reusable threadId.

About

Any operator the Gmail search box understands works here, because the query runs in your own signed-in Gmail, and each match comes back with a threadId the other Gmail scripts accept. Say a bookkeeper closing September runs has:attachment filename:pdf subject:(invoice OR receipt) after:2026/09/01 before:2026/10/01 with limit set to 50. She gets 34 threads, comfortably under the cap, hands each threadId to download_attachment and drops the PDFs into the accounting tool, binning the inline logos that come along. Each result is a thread, and only the first results page is read: 20 rows by default, 50 at most. On personal accounts Gmail's default sort for search is Most relevant, so those rows are the top of a ranking, not necessarily the newest matches. The date field is Gmail's tooltip text in your account language, so parse it before sorting. On a long back-and-forth, sender is whoever is listed first on the row, often not the last person to reply.

Input

query required

Gmail search query; full native operator syntax (from:, subject:, has:attachment, after:...).

limit optional

Max rows to return (1-50, default 20).

account optional

Gmail account address to act as (authuser pin). Omit for u/0.

Output

n required
query required
emails required

Example output

Shape only: placeholder values generated from the output schema, not a real run.

{ "n": 3, "query": "…", "emails": [ {} ] }

FAQ

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).
Ask an AI agent connected to Reduck to run reduck/mail.google.com/search_emails, or run it from a terminal with the Reduck CLI: npx @reduck-ai/cli@latest run --script reduck/mail.google.com/search_emails
You do not need one. "Search Gmail" 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: query. Optional: limit, account.
It returns n, query, emails.
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 only reads. It looks things up on mail.google.com and changes nothing there.
Ask an AI agent connected to Reduck to run reduck/mail.google.com/search_emails, or run it from a terminal with the Reduck CLI: npx @reduck-ai/cli@latest run --script reduck/mail.google.com/search_emails
It is part of Reduck's official curated catalogue.
Search Gmail reads only the first page of results: 20 threads unless you pass a higher limit, 50 at most, and fewer if your Gmail Maximum page size setting is under 50. The output carries no total match count, so when n equals your limit there may be more; split the query into date windows with after: and before: and narrow each window until n comes back below the limit.
Google's filtering guide says the Gmail API's q parameter skips two things the search box does: thread-wide search, and alias expansion, where a search on your main Workspace address also catches mail sent from your aliases. Search Gmail uses the search box itself, so it gets both. The API is free for standard use and can page through a whole mailbox at up to 500 threads per call, but every scope that allows a query is restricted, so an app offered to the public must pass Google's verification, while personal use under 100 users, testing mode and apps internal to a Workspace organization are exempt.
Gmail leaves Spam and Trash out of a standard search, and Search Gmail runs that same search, so a plain query skips them. Add in:anywhere to the query when you are hunting for a confirmation or password reset email that may have been filtered.
The threadId from Search Gmail feeds archive_email, add_label, trash_email and mark_read. trash_email and mark_read only look through the first four All Mail list pages (about 200 threads at 50 per page, fewer with a smaller page size), so an old match can be out of their reach, while archive_email falls back to opening the thread by its id when it is not among the newest Inbox pages.

Related scripts

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.

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