Pagination

Inbox lists, thread lists, messages within a thread, inbox exports, and webhook lists support cursor pagination. Consult each endpoint for supported parameters; not every list is paginated.

Request the next page

curl --fail-with-body --silent --show-error --get \
  "$MAILACTOR_API_URL/v1/inboxes" \
  -H "x-api-key: $MAILACTOR_API_KEY" \
  --data-urlencode "limit=20" \
  --data-urlencode "cursor=$NEXT_CURSOR"

Omit cursor for the first request. Pass back the response's nextCursor unchanged for the next request. Stop when it is null. limit is between 1 and 100; smaller pages may help if content-heavy reads return 413.

Cursors are opaque and scoped to their owning tenant/resource. Never decode, modify, or reuse one across inboxes or organizations.

Know the response container

Lists are newest-first. A thread summary does not contain messages; call the thread endpoint to read its messages.

Read every page

Download the Node.js pagination reader. It passes cursors with URL encoding, stops only at nextCursor: null, and throws if the deadline expires, the response is invalid, or any request fails. It does not silently return a partial inventory as complete.

import { readMailactorPages } from './read-pages.mjs';

for await (const inbox of readMailactorPages('/v1/inboxes', 'inboxes', {
  apiKey: process.env.MAILACTOR_API_KEY,
  deadline: Date.now() + 60_000,
})) {
  // Persist this inbox before continuing; a later page can still fail.
  console.log(inbox.id, inbox.address);
}

Use baseUrl only when targeting a trusted API deployment. This is a read-only helper: retries and durable storage belong to your application. On 429, honor the helper error's retryAfter property, which copies the HTTP Retry-After header (it is not a field in the API JSON error body); on a content-size 413, retry a new traversal with a smaller limit. If a traversal fails, preserve what you saved, mark it incomplete, and restart with ID deduplication. Never delete an inbox based on an incomplete export.

A nonfinal response contains a string in nextCursor (for example, "opaque-cursor-from-server"); that example text is not a usable cursor. The next request must reuse the actual server value. A final page returns JSON null, not the string "null".

Handle concurrent arrivals

A new message can move a thread toward the top of the list while you are paging. Deduplicate by resource ID. After a complete pass, restart at page one and reconcile until a complete pass adds no unseen IDs, or your deadline expires.

Pagination is not a snapshot guarantee. For a continuously active inbox, use webhook notifications plus periodic reconciliation and do not wait forever for a perfectly stable inventory.