Pagination

How MachineMail list endpoints page with limit, page_token and next_page_token: walking every page, sort order, and the endpoints that page differently.

Source: https://machinemail.dev/docs/reference/pagination

List endpoints page with three query parameters and return three fields, the same as AgentMail.

{
  "count": 50,
  "limit": 50,
  "next_page_token": "eyJvIjo1MH0",
  "inboxes": [ ... ]
}

The items are under a key named after the resource: inboxes, messages, threads, drafts, webhooks, deliveries, domains, pods, api_keys, entries, suppressions, events, agent_registrations.

Walking every page

async function listAll(path: string, key: string) {
  const items = [];
  let pageToken: string | undefined;
  do {
    const url = new URL(`https://api.machinemail.dev${path}`);
    url.searchParams.set('limit', '500');
    if (pageToken) url.searchParams.set('page_token', pageToken);
    const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.MACHINEMAIL_API_KEY}` } });
    const page = await res.json();
    items.push(...page[key]);
    pageToken = page.next_page_token;
  } while (pageToken);
  return items;
}

const inboxes = await listAll('/v0/inboxes', 'inboxes');

Page tokens

Treat tokens as opaque. Today a token encodes an offset into the result set, so:

• Items created while you page can shift later pages: an item can appear twice or be skipped. For a stable feed of changes, read the event log with after=<event_id> instead.
• A token that cannot be decoded is ignored and the list starts again from the first page. It is not an error.
• Use a token with the same filters and sort order that produced it.

Sort order

Endpoints that page differently