List messages
Returns messages newest first, in arrival order. Page with before: pass the previous response's next_cursor to get the next page. A cursor page costs the same at any depth and does not shift when new mail arrives, where offset does both. offset is still accepted, but not together with before. starred, unread, has_attachments and tag narrow the listing on the server; they combine with AND, with each other and with q. total counts the messages matching q and the filters, before pagination is applied.
Parameters
Query Parameters
Full-text search query (matches subject, body, sender, recipients)
Maximum number of results to return. Values outside 1 to 200 (0 and negatives included) are clamped into that range rather than rejected; the response's limit reports the value applied. A value that is not an integer is a 400.
50Number of results to skip. A negative value is treated as 0. Kept for compatibility; prefer before, which it cannot be combined with.
0Keyset cursor: the id of a message. Returns only messages strictly older than it, in the same order. Use a previous response's next_cursor. Works with q. An id that names no stored message is a 400 with code: unknown_cursor.
When true, only starred messages. false does not filter: it is the same as leaving the parameter out, not its negation. Only the literals true and false are accepted; anything else, 1 included, is a 400. If repeated, the last value wins.
When true, only messages not marked as read. false does not filter: it is the same as leaving the parameter out, not its negation. Only the literals true and false are accepted; anything else, 1 included, is a 400. If repeated, the last value wins.
When true, only messages with at least one attachment. false does not filter: it is the same as leaving the parameter out, not its negation. Only the literals true and false are accepted; anything else, 1 included, is a 400. If repeated, the last value wins.
Only messages carrying this tag, compared exactly and case-sensitively. May repeat (tag=a&tag=b): a message matches if it carries any of the given tags. More than 20 is a 400.
20Responses
Paginated list of message summaries. Sent with Cache-Control: no-store.