Pagination

Lists that can grow long are paginated with a cursor. They return a page of results, newest first, and a nextCursor to fetch the page after it.

{
  "data": [
    { "id": "email_01K6B2Y4ZP9R3M7T8V5N2QXW4C", "subject": "Welcome to Acme" },
    { "id": "email_01K6B2X1QH4D8S2F6G9J3K7L0M", "subject": "Your sign-in link" }
  ],
  "nextCursor": "MjAyNi0wOS0yNlQxNDowNTozMS4xMjNafGVtYWlsXzAxSzZCMlgxUUg0RDhTMkY2RzlKM0s3TDBN"
}

ParametersCopy Anchor Link

Pass the same filters on every page. The cursor only remembers where the last page ended, not the filters.

nextCursor is null on the last page. Treat the cursor as an opaque string: its format can change.

Results are ordered by creation time, newest first. New items created while you page through don't shift the pages you haven't read yet, because the cursor points at a position in time rather than an offset.

Which endpoints are paginatedCopy Anchor Link

On emails and events (including the admin versions), a limit outside 1 to 100 fails with 400 invalid_query. On the other paginated lists it is clamped into range instead. The admin suppression list defaults to 50 per page and allows up to 200.

Reading every pageCopy Anchor Link

import { Flaresend, type EmailRecord } from '@flaresend/client';

const flaresend = new Flaresend({
  apiKey: process.env.FLARESEND_API_KEY!,
  baseUrl: 'https://mailer.example.com',
});

const bounced: EmailRecord[] = [];
let cursor: string | undefined;

do {
  const page = await flaresend.emails.list({ status: 'bounced', limit: 100, cursor });
  bounced.push(...page.data);
  cursor = page.nextCursor ?? undefined;
} while (cursor);

Cursors use only URL-safe characters (letters, digits, - and _), so you can put them in a query string as they are. A cursor that can't be read is ignored, and you get the first page.