# Pagination

> Cursor-based pagination for list endpoints.

List endpoints that can return many rows use **keyset (cursor) pagination**,
which stays consistent even as new mail arrives.

## How it works

Pass `limit` to control page size (default 50, max 100). When more results
exist, the response includes a non-null `nextCursor`. Pass it back as `cursor`
to fetch the next page. When `nextCursor` is `null`, you've reached the end.

```json
{
  "data": [ { "id": "em_abc123" }, { "id": "em_def456" } ],
  "nextCursor": "MjAyNi0wNy0yMFQxMDozMDowMC4wMDBafmVtX2RlZjQ1Ng"
}
```

## Iterating

<CodeGroup>

```bash cURL
# First page
curl "https://inboundr.net/api/v1/emails?limit=50" \
  -H "Authorization: Bearer $INBOUNDR_API_KEY"

# Next page
curl "https://inboundr.net/api/v1/emails?limit=50&cursor=MjAyNi0w..." \
  -H "Authorization: Bearer $INBOUNDR_API_KEY"
```

```ts TypeScript
let cursor: string | null = null;
do {
  const url = new URL("https://inboundr.net/api/v1/emails");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);

  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.INBOUNDR_API_KEY}` },
  });
  const page = await res.json();
  for (const email of page.data) {
    // handle email
  }
  cursor = page.nextCursor;
} while (cursor);
```

```php PHP
<?php
$cursor = null;
do {
    $url = "https://inboundr.net/api/v1/emails?limit=100";
    if ($cursor) $url .= "&cursor=" . urlencode($cursor);

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            "Authorization: Bearer " . getenv("INBOUNDR_API_KEY"),
        ],
    ]);
    $page = json_decode(curl_exec($ch), true);
    curl_close($ch);

    foreach ($page["data"] as $email) {
        // handle $email
    }
    $cursor = $page["nextCursor"];
} while ($cursor);
```

</CodeGroup>

<Note>
  Results are ordered newest-first by received time. An invalid cursor returns a
  `400` with `{ "error": "Invalid cursor" }`.
</Note>