List Threads
Retrieve the threads in an inbox, filtered by folder, label, and read status.
GET
A thread is a conversation within an inbox, made up of one or more messages.
To find threads by text, sender, recipient, attachment, or date, use Search
Threads.
Path Parameters
Query Parameters
string
Comma-separated folders to list:
inbox, archive, spam, sent, or
trash. A thread is returned when any of its emails is in one of them, so a
thread in inbox with an email you sent matches both inbox and sent.
Defaults to inbox, or inbox,archive,sent when labels is set. spam and
trash are only included when you name them.string
Comma-separated label IDs. Returns threads with any of these labels. Up to
50 IDs. An ID that doesn’t exist in the inbox returns a 404.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. To filter by date, use Search
Threads with
start_date.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. To filter by date,
use Search Threads with end_date.Folders
Every thread sits in exactly one folder within its inbox.
You can move a thread to
inbox, archive, spam, or trash. sent is
assigned automatically.
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.