Pagination

If you've got a non-trivial number of subscribers or emails, you'll almost certainly need to paginate through them at some point.

Buttondown's API uses number-based pagination: you'll need to specify the page number you want to retrieve with the page query parameter. Like so:

curl 'https://api.buttondown.com/v1/subscribers?page=2'

If you don't specify a page, we'll assume you want the first page of results. This is because pagination is technically a subset of filtering, and the same principles apply!

Additionally, responses that can be paginated always include a next field that contains the URL for the next page of results. If you're on the last page, the next field will be null. This looks something like the following:

  {
    "count": 100,
    "next": "https://api.buttondown.com/v1/subscribers?page=3",
    "previous": "https://api.buttondown.com/v1/subscribers?page=1",
    "results": [
      ...
    ]
  }

In addition to the next and previous fields in the response body, Buttondown also returns RFC 5988 Link headers on paginated responses. This makes it easy to navigate pages using standard HTTP tooling:

Link: <https://api.buttondown.com/v1/subscribers?page=3>; rel="next", <https://api.buttondown.com/v1/subscribers?page=1>; rel="prev"

The Link header will only include rel="next" and rel="prev" links when the corresponding pages exist — so the first page won't have a rel="prev" link, and the last page won't have a rel="next" link.

You can easily paginate through results by following the next field until it's null. Here's an example in JavaScript:

const fetchSubscribers = async () => {
    let subscribers = [];
    let next = "https://api.buttondown.com/v1/subscribers";

    while (next) {
        // Note that authentication is not handled in this code snippet,
        // for clarity's sake!
        const response = await fetch(next);
        const data = await response.json();

        subscribers = subscribers.concat(data.results);
        next = data.next;
    }

    return subscribers;
};