Pagination
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).
{
"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.
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:
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.