Pagination

List endpoints (GET /emails, /domains, /api-keys, /webhooks, /audiences, /audiences/{id}/contacts, /broadcasts, /suppressions) share one cursor-based scheme.

Parameter	Description
limit	Items per page, 1 to 100. Default 20.
after	An item id. Returns the page of items older than it (the next page).
before	An item id. Returns the page of items newer than it (the previous page).

Use only one of after and before; both together return 422. Results are newest first. Cursors are item ids (UUIDv7, which sort by creation time), so pages stay stable while new items arrive.

Response

{
  "object": "list",
  "has_more": true,
  "data": [
    { "object": "email", "id": "0192e1c4-7a3c-7a02-8e10-6c0f9d7a2b31", "...": "..." },
    { "object": "email", "id": "0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10", "...": "..." }
  ]
}

has_more tells you whether another page exists in the direction you were paging.

Walk every page

Node.js

import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost();

let after: string | undefined;
for (;;) {
  const { data, error } = await spacepost.emails.list({ limit: 100, after });
  if (error) throw new Error(error.message);
  for (const email of data.data) console.log(email.id, email.last_event);
  if (!data.has_more) break;
  after = data.data[data.data.length - 1]!.id;
}

cURL

curl "https://api.spacepost.dev/emails?limit=100" -H "Authorization: Bearer $SPACEPOST_API_KEY"
curl "https://api.spacepost.dev/emails?limit=100&after=0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10" -H "Authorization: Bearer $SPACEPOST_API_KEY"

Python

after = None
while True:
    params = {"limit": 100, **({"after": after} if after else {})}
    page = requests.get("https://api.spacepost.dev/emails", headers=h, params=params).json()
    for email in page["data"]:
        print(email["id"], email["last_event"])
    if not page["has_more"]:
        break
    after = page["data"][-1]["id"]

Notes

• List responses for emails omit html and text; fetch one email to get its body.
• List responses for domains omit records; fetch one domain to get them.
• A malformed cursor returns 422 validation_error (“Invalid pagination cursor”).