Skip to Content

A TypeScript SDK listing: awaited, one page as the API answers it; iterated, every item of every page, each page fetched as the loop reaches it.

An operation that takes a cursor and answers a page with a nextCursor is a listing, and its method answers a PagePromise:

const page = await openemail.messages.list(mailboxId, { limit: 50 })    // one page, nextCursor and all

for await (const message of openemail.messages.list(mailboxId)) {}     // every message of every page

for await (const page of openemail.messages.list(mailboxId).pages()) {} // page by page

const all = await openemail.routes.list({ domain: 'example.com' }).all() // every item in one array
  • Awaited, it is its first page, exactly as the API answers it: the items and the nextCursor, typed by the method's own page type (MessagesListResult).
  • Iterated with for await, it is every item of every page, each page fetched as the loop reaches it. Stop the loop and no further page is fetched.
  • .pages() gives each page whole, for a loop that needs the cursor; .all() gathers every item into one array. A listing can be long: iterate it where it might not fit in memory.
  • .withResponse() answers the first page with the Response it came in (Responses and headers).

How it pages

  • Nothing is sent until it is awaited or iterated, and its first page is fetched once, however often it is asked for.
  • Each next page is the same call with the cursor the last page named; the other options stay as they were, as the API asks of a crawl (its filters, its order, its sort).
  • A page whose nextCursor is missing, empty, or a cursor already fetched is the last, so a cycle cannot loop.
  • Where a page holds several lists, the item is the one the page is about: an event log's events, a search's results (or, with fields: 'ids', its ids).

The API's own rules for cursors are in the API reference's overview: limit caps at 200 on most listings, and a cursor is opaque. Each listing's page in this reference says its item type, for example messages.list.

On this page