Opaque cursor from a previous response to fetch the next page

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

Filter messages by agent ID

Filter messages by conversation thread ID

Filter messages by communication channel

Filter messages by direction (inbound or outbound)

Filter messages by delivery status

Filter to one inbox — messages delivered to it (inbound) or sent from it (outbound). The precise way to read a single mailbox when an agent owns several.

Filter by sender address, matched exactly (case-sensitive). On inbound mail this is the counterparty; on outbound it is the agent identity the mail was sent from.

Filter by recipient address, matched exactly (case-sensitive). Note that outbound messages store every recipient in one comma-joined value, so an exact filter matches a multi-recipient send only when given that same joined string — prefer inboxId to scope outbound mail to a mailbox.

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.

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.

How to treat messages moved to Trash. exclude (default) hides them, so deleted mail disappears from every ordinary listing. only returns nothing but Trash. include ignores the distinction. Deletion is reversible — see DELETE /messages/{id} and POST /messages/{id}/restore.