# Listings

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`:

```ts
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](/docs/sdks/typescript/responses)).

## 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](/docs/api/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`](/docs/sdks/typescript/messages/list).
