Skip to main content
Searches the mailbox and returns a compact hit list without full message bodies — multi-term queries rank messages matching more terms first (newest-first within equal matches), everything else is newest-first. Combine free text with any of the structured filters; at least one filter is required. Hits include a body snippet and attachment metadata when available, so download_attachment can often be called directly from the search result. Fetch a full message with get_email when you need recipients or the complete body.
Filter first, search second. Transactional mail — tickets, invoices, orders, bookings, confirmations — rarely names its own type in the subject or body: a cinema booking is titled after the film, an invoice after the vendor. For a request like “find my tickets” or “show the invoice from X”, reach for keywords plus an after/before window rather than a free-text query. Use query for words the sender actually wrote.

​
Parameters

​
string
Free-text search over subject, body, and addresses. 1–500 characters. Terms are matched independently and combined with OR — a message matches if it contains any of the terms — and messages matching more terms rank first, with each hit showing a matched: X/N terms line. Wrap a phrase in double quotes ("Google Workspace") to require all its words in the same field, rather than any one of them anywhere. To narrow a search, combine query with the structured filters (from, keywords, after/before) instead of adding more terms; only the first 10 terms are used.
​
string
Only messages received on or after this UTC ISO 8601 timestamp, e.g. 2026-04-01T00:00:00Z.This filters the received date, not any date the message talks about. A confirmation arrives before the event it confirms, so for an event-anchored request (“yesterday’s show”, “last week’s flight”) start the window a booking lead time — days to weeks — before the event rather than on the event day. Paired with an email-type filter, a wide window no longer drowns the target in newsletter noise.
​
string
Only messages received strictly before this UTC ISO 8601 timestamp, e.g. 2026-07-01T00:00:00Z. Also the received date: for an event-anchored request, end the window at the event rather than bounding it to the event day.
​
string
Substring match on the sender’s name or address. 1–200 characters.
​
string[]
Filter by the classified email type; multiple values combine with OR. At least one value when present. Valid values:Every value except todo is a classified email type, and each message carries exactly one of them: receipt returns receipts and not orders. todo is a flag orthogonal to the taxonomy, so it combines with any type.Messages analyzed before classification existed carry no type. If a type filter returns nothing, fall back to a free-text query.
​
string
Restrict to a named mailbox/folder, e.g. Inbox.The standard places — Inbox, Sent, Archive, Drafts, Trash, Junk — are resolved to the folder holding that special-use role, so they match whatever the server actually names it (Sent finds a mailbox called Sent Items). Any other value matches a folder name exactly, and a place name falls back to a name match when no folder carries the role.
​
integer
default:"20"
Maximum results, 1–100.

​
Example

Call
Result
A filter-only call needs no free text at all — the shape to reach for when the request names a kind of mail rather than its content. Here the window starts three weeks before the show, because the confirmation arrived when the seats were booked, not when the film ran:
Call
Messages with no tags omit the tags: line. Messages with no preview omit the snippet: line. Hits from a multi-term query carry a matched: X/N terms line and are ordered by that count (newest-first within equal counts); single-term and filter-only results are newest-first. Hits carrying files list non-inline attachments with filename, media type, size, and blobId; if the server reports attachments but no non-inline parts are available, the hit falls back to attachments: yes. An empty result returns No messages matched. When the result filled limit, it ends with a truncation note — more matches may exist beyond the page (and for multi-term queries, match counts are computed within a newest-first window per term), so narrow the date range or raise limit.

​
Errors

  • Provide at least one filter: query, after, before, from, keywords, or mailbox. — the call had no filter.
  • query contains no searchable terms. — the query value was only whitespace or empty quotes.
  • Mailbox not found: <name>. Available folders: ... — the mailbox value matched neither a folder name nor a special-use role. The listed folder names say what to ask for instead.