Search Threads
Find threads in an inbox by text, people, attachments, and dates.
GET
Search finds threads by the text of their emails, who sent or received them,
whether they have attachments, and their dates.
Path Parameters
Query Parameters
string
Free text to search for in the subject, body, sender, recipients, and
attachment names.
string
Comma-separated senders. Up to
20 values.string
Comma-separated recipients. Up to
20 values.string
Comma-separated CC recipients. Up to
20 values.string
Comma-separated BCC recipients. Up to
20 values.boolean
true matches emails with an attachment. false matches emails without one.string
Matches emails sent on or after this date. Accepts a date like
2026-09-01 or
an ISO 8601 timestamp, in UTC unless the timestamp has an offset.string
Matches emails sent on or before this date. Same formats as
start_date. A
date covers that whole day, so start_date=2026-09-01&end_date=2026-09-30
covers all of September.string
Comma-separated folders to search.
inbox: The default. The thread holds at least one received message.archive: The thread was archived.spam: The thread was marked as spam.trash: The thread is scheduled for deletion in 30 days.sent: Threads whose messages are all outbound.
string
Comma-separated label IDs. Returns threads with any of these labels. Up to
50 IDs.boolean
true returns threads where every email is read. false returns threads with
at least one unread email.number
Number of threads to return. Default is
20, maximum is 100, minimum is
1.string
The ID of the last thread on the current page. Returns the next, older page.
Must be a thread ID.
string
The ID of the first thread on the current page. Returns the previous, newer
page. Cannot be combined with
after. Must be a thread ID.How matching works
querymatches when every word appears somewhere in the email. A quoted phrase like"late fee"must appear word for word, and-wordor-"a phrase"excludes emails that contain it.query=invoice -draftfinds emails that mentioninvoicebut notdraft.- A comma means any of:
from=isabella@example.com,carolina@example.commatches emails from either. Different parameters combine, so a thread must match all of them. folders,labels, andreadapply to the thread.query,from,to,cc,bcc,has_attachment,start_date, andend_datemust all match the same email in the thread.- When any of these email filters is set, the matching email must itself be in
one of
folders. Forsent, that means an email the inbox sent. - When more than 10,000 threads match, search covers the 10,000 with the newest matching email.
Response Fields
string
Always
list.boolean
Whether more threads exist beyond this page. Pass the last thread’s
id as
after to continue.array
The matching threads, most recently active first.
Errors
Validation errors return422 with the name validation_error.