Pagination

How it works#

Paginated list endpoints use page numbers. You ask for a page and a page size; the response returns that slice plus the totals you need to know when to stop.

pageintegerdefault 1

Which page to return, starting at 1.

per_pageintegerdefault 20

Items per page, from 1 to 100.

Both are query parameters and combine with each endpoint's own filters:

curl "https://api.poststack.dev/emails?page=2&per_page=50&status=bounced" \
  -H "Authorization: Bearer $POSTSTACK_API_KEY"

The response puts the items in data and the paging state in meta:

{
  "data": [
    { "id": 48213, "publicId": "em_k3v9x2m8q1w7r4t6y0p5n2bz", "status": "bounced", "…": "…" },
    { "id": 48190, "publicId": "em_c8n1q4w0z7x2v5b9m3k6j1hd", "status": "bounced", "…": "…" }
  ],
  "meta": {
    "page": 2,
    "perPage": 50,
    "total": 137,
    "totalPages": 3
  }
}

dataobject[]

This page's items, in the endpoint's order (see the table below).

meta.pageinteger

The page you got.

meta.perPageinteger

The page size used.

meta.totalinteger

Items matching your filters across all pages.

meta.totalPagesinteger

ceil(total / perPage) — 0 when nothing matches.

Walking every page#

Request page 1, then keep going until page reaches meta.totalPages. Use per_page=100 to make the fewest requests. None of the SDKs has an auto-paging iterator, so the loop is yours:

import { PostStack } from '@poststack.dev/sdk';

const poststack = new PostStack(process.env.POSTSTACK_API_KEY!);

const seen = new Set<string>();
for (let page = 1; ; page++) {
  const { data, meta } = await poststack.emails.list({ page, per_page: 100, status: 'bounced' });
  for (const email of data) {
    if (seen.has(email.publicId)) continue; // a new row can shift an item onto the next page
    seen.add(email.publicId);
    // ...handle email
  }
  if (page >= meta.totalPages) break;
}

page=1
while :; do
  body=$(curl -sS "https://api.poststack.dev/emails?page=$page&per_page=100" \
    -H "Authorization: Bearer $POSTSTACK_API_KEY")
  echo "$body" | jq -c '.data[]'
  [ "$page" -ge "$(echo "$body" | jq '.meta.totalPages')" ] && break
  page=$((page + 1))
done

import os
from poststack import PostStack

client = PostStack(api_key=os.environ["POSTSTACK_API_KEY"])

page = 1
while True:
    res = client.emails.list({"page": page, "per_page": 100})
    for email in res["data"]:
        ...  # handle email
    if page >= res["meta"]["totalPages"]:
        break
    page += 1

for page := 1; ; page++ {
	res, err := client.Emails.List(ctx, &poststack.ListEmailsParams{
		Page:    poststack.IntPtr(page),
		PerPage: poststack.IntPtr(100),
	})
	if err != nil {
		return err
	}
	for _, email := range res.Data {
		_ = email // handle email
	}
	if page >= res.Meta.TotalPages {
		break
	}
}

Pages are computed at request time with an offset, not held open for you. If an item is created or deleted while you are paging, everything after it shifts by one: on a newest-first list, a new email arriving between page 1 and page 2 pushes the last item of page 1 onto page 2, so you see it twice. De-duplicate on the ID as above. For GET /emails you can also fix the window with date_to set to the time you started, so new sends can't enter the result.

Limits and errors#

• Out-of-range values are rejected, not clamped. per_page=500, per_page=0, page=0 or a non-number answer 400, naming the parameter.
• A page past the end is not an error. It returns 200 with an empty data and the real meta.total.
• cursor does nothing. Some endpoints accept a cursor parameter without complaint, but it is ignored — you get page 1 (or whatever page says). Don't build on it.
• List reads aren't rate-limited per endpoint, but they are subject to the per-IP edge limit of 30 requests a second.

HTTP/1.1 400 Bad Request

{
  "error": "per_page: Too big: expected number to be <=100"
}

Paginated endpoints#

These return { data, meta } as described above, unless the table says otherwise.

Lists that aren't paginated#

These return every item in one response, under a key named after the resource. They take no page or per_page; any you send are ignored.

Lists capped by a limit parameter

Three broadcast reports take limit instead of pages. There is no way to get past the maximum.

Troubleshooting#

Next steps