Paging Through a Mailbox
How it works
1.
mailbox_uid and, optionally, limit (1 to 50).2.
data.pagination.next_page_token from the response.3.
mailbox_uid, limit, labels and q, and add page_token set to that string.4.
next_page_token is null. That page is the last one, and hasMore is false.200 (shortened to the paging fields){
"error": false,
"message": "Messages retrieved successfully",
"data": {
"messages": [],
"pagination": {
"page": 1,
"limit": 50,
"hasMore": true,
"next_page_token": "09284715563019847261"
}
}
}Things to know
next_page_token as an opaque string. Its format depends on the mailbox provider, and it can be long. Send it back exactly as you received it, and URL-encode it in a query string. If you would rather not encode it, send the request as POST with a JSON body.400 with Invalid or expired page_token, start again from the first page.page is accepted but has no effect: page=2 returns the first page again. Use page_token.page_token needs mailbox_uid. Without it you get 400 with page_token requires mailbox_uid. Listing without mailbox_uid returns the newest messages across the workspace in one response, with no paging.labels for each label: labels=INBOX&labels=UNREAD.When a page fails
429: wait for the number of seconds in Retry-After when it is present, or a few seconds when it is not, and request the same page again with the same page_token. A smaller limit makes this less likely.500: retry the same page with backoff. If it keeps failing, contact support.429{
"code": 429,
"message": "Too many concurrent requests for user."
}Modified at 2026-11-11 09:37:16