Request
GET /api/v1/mail/messages?folder=inbox&limit=25&offset=0
Authorization: Bearer <key with mail.read>Query values are optional. `folder` accepts `inbox`, `sent`, `drafts`, `archive`, or `trash`. `limit` defaults to 50 and must be 1–100. `offset` defaults to 0 and must be 0–10,000.
Response fields
The response contains `ok` and `messages`. Each message can include its ID, folder, direction, from/to/cc, reply-to, subject, text, preview, attachment metadata, read/starred state, delivery status, and timestamps. Values not relevant to the message lifecycle may be `null`.
Content and privacy
Message body and recipient data are sensitive. Attachment entries provide metadata only; file contents are not included. Responses are non-cacheable. Store or forward the returned material only where your integration’s authorization and retention policy permits.
Read requests do not mutate read, starred, or folder state.
Pagination
Use bounded offset pagination. A page shorter than the requested limit usually indicates that no more matching rows remain. Avoid excessive offsets; the upper bound is 10,000. The API currently does not return a cursor token or guarantee a multi-page snapshot while new mail arrives.