---
title: Pagination
slug: pagination
docTags: 
createdAt: 2026-06-02T09:00:53.233Z
---

List endpoints return a consistent envelope so you can page through results the
same way everywhere.

## The list envelope

Only **list/collection** responses are wrapped. Single resources are returned
bare (the object is the response body directly).

```json
{
  "data": [
    { "...": "..." },
    { "...": "..." }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  }
}
```

- **`data`** — the array of resources for this page.
- **`has_more`** — `true` if there are more results after this page.
- **`next_cursor`** — an opaque cursor for the next page, or `null` when there
  are no more results.

Every list returns this envelope from launch — even endpoints that don't
paginate today return `next_cursor: null` and `has_more: false`. Build for it
once and it works across the API.

## Paging through results

Pass the `next_cursor` value back as the `next` query parameter to fetch the
following page. Treat the cursor as opaque — don't parse or construct it.

```bash
curl "https://api.mailfloss.com/v1/jobs?per_page=25" \
  -H "Authorization: Bearer YOUR_API_KEY"
# -> { "data": [...], "pagination": { "next_cursor": "ZXhhbXBsZQ", "has_more": true } }

curl "https://api.mailfloss.com/v1/jobs?per_page=25&next=ZXhhbXBsZQ" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

A typical loop — keep going until `has_more` is `false`:

```python
import requests

session = requests.Session()
session.headers["Authorization"] = "Bearer YOUR_API_KEY"

url = "https://api.mailfloss.com/v1/jobs"
params = {"per_page": 100}
jobs = []

while True:
    page = session.get(url, params=params).json()
    jobs.extend(page["data"])
    if not page["pagination"]["has_more"]:
        break
    params["next"] = page["pagination"]["next_cursor"]
```

## Page size

Control page size with `per_page`. Defaults vary by endpoint, and the maximum
is **100**:

| Endpoint                                                 | Default `per_page` |
| -------------------------------------------------------- | ------------------ |
| `GET /v1/jobs`                                           | 25                 |
| `GET /v1/users`                                          | 25                 |
| `GET .../connections/{id}/blacklist` and `.../whitelist` | 50                 |

Requesting more than 100 is capped at 100. See the API reference for the
per-endpoint default.