Skip to main content
GET
cURL

Authorizations

Authorization
string
header
required

JWT Bearer token obtained from authentication. Pass as: Authorization: Bearer

Query Parameters

cursor
string

Opaque cursor from a previous response to fetch the next page

Pattern: ^[cC][^\s-]{8,}$
limit
integer
default:20

Maximum number of items to return per page (1–100, default 20)

Required range: 1 <= x <= 100
agentId
string

Filter emails by agent ID

Pattern: ^[cC][^\s-]{8,}$
direction
enum<string>

Only return received (INBOUND) or sent (OUTBOUND) email

Available options:
INBOUND,
OUTBOUND
threadId
string

Only return email in this thread (see GET /threads)

Pattern: ^[cC][^\s-]{8,}$
from
string

Only return email whose sender address matches this value (case-insensitive, exact address match)

to
string

Only return email addressed to this recipient (case-insensitive). Matches if the address appears anywhere in the message's recipient list, not only as the first recipient.

after
string<date-time>

Only return email created strictly after this ISO-8601 timestamp

before
string<date-time>

Only return email created strictly before this ISO-8601 timestamp

labels
string[]

Filter to messages carrying ALL of these labels (e.g. urgent + unread means urgent AND still unread). Case-insensitive. System labels: unread, read, archived, spam.

Maximum array length: 50
Required string length: 1 - 64
includeSpam
boolean
default:false

Include messages classified as spam on arrival. They are excluded by default. Naming spam in labels also counts as asking for it, so a deliberate spam query is never silently emptied by this default.

includeArchived
boolean
default:false

Include messages carrying the archived label. They are excluded by default, so archiving actually removes mail from a listing rather than only tagging it. Naming archived in labels also counts as asking for it (and returns ONLY archived mail); use this flag instead to see archived mail mixed in with the rest.

Response

200 - application/json

OK

Paginated list of email messages

items
object[]
required

Array of email message resources matching the query

pagination
object
required

Pagination metadata for retrieving additional pages