Reference

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#

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"

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
$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);

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