Zapmail
Overview
API Reference
Overview
API Reference
  1. Overview
  • Introduction
  • Quickstart
  • Authentication
  • MCP
  • Versioning
  • Errors
  • Webhooks
  • Rate Limits
  • Pagination
  • Changelog
  • Capabilities
    • Mailboxes
    • Pre-Warmed
    • Deliverability
    • Domains
    • Export to Sequencer
    • Zapbox
    • Team Management
    • ZapShield
    • ZapCare
    • AI Insight
    • Deliverability Tests
    • ZapSites
    • Zapwarm
    • ZapPulse
  • Billing
    • Understanding Zapmail billing
    • Wallet
  1. Overview

Pagination

List endpoints return results one page at a time. You choose the page with page and the page size with limit. The pagination fields in the response, and the defaults, differ from endpoint to endpoint, so read the endpoint page before you write a paging loop.

Request parameters#

ParameterDefaultDescription
page11-based page number.
limit10Number of items per page. Many endpoints set their own default.
Send both parameters in the query string. Endpoints that read a JSON body (for example POST /domains) also accept them in the body. If a value is present in both places, the query string wins.
Both are validated before the endpoint runs. A page below 1, a negative limit, or a value that is not a number returns 400 with the message Invalid pagination parameters. Endpoints can add stricter rules and return 422.
Treat limit as at least 1. A limit of 0 passes the shared check, but several endpoints then substitute their own default instead of returning an empty page.
Where an endpoint page states a maximum for limit (for example 100), stay within it. Behaviour above the maximum is not guaranteed to be the same on every endpoint.

Response fields#

Most list endpoints return these fields inside data, next to the array of items:
{
  "status": 200,
  "message": "Domains fetched successfully",
  "data": {
    "totalSearchedCount": 42,
    "currentPage": 1,
    "nextPage": 2,
    "totalPages": 5,
    "domains": []
  }
}
FieldDescription
totalSearchedCountNumber of items that match your filters, across all pages.
currentPageThe page returned.
nextPageThe next page number. It is not clamped to totalPages, so it can point past the last page. Do not use it as an end-of-list signal.
totalPagesTotal number of pages for the current limit.
The name of the total differs, and some endpoints nest the fields in a pagination object:
EndpointDefault limitMaximum limitWhere the total is
List Domains10None stateddata.totalSearchedCount
List Mailboxes10None stateddata.totalSearchedCount (pages count domains, not mailboxes)
List Subscriptions10None stateddata.totalSearchedCount, and data.totalUnfilteredCount
List Workspaces10None stateddata.totalSearchedCount
List Workspace Members10None stateddata.totalSearchedCount
Search Available Domains50None stateddata.pagination.total
List Aged Domains20100data.pagination.totalCount
List Pre-Warmed Domains10None stateddata.total
List Pre-Warmed Subscriptions10None stateddata.total
List ZapShield Allocated Domains50100data.totalSearchedCount
List Deliverability Test Orders10100data.pagination.totalSearchedCount
List Zapbox Connected Accounts50100pagination.totalCount at the top level of the response
Search Zapbox Emails50100No total. The response is a plain array.
GET /webhooks/deliveries10None stateddata.total only
The table lists the endpoints most integrations page through. Every other list endpoint documents its own fields and defaults.
Things to know:
GET /webhooks/endpoints is not paginated.
GET /workspaces/invitations accepts page and limit but returns every invitation regardless.
Some endpoints cut the page before they apply a filter, so a page can contain fewer items than limit even when more pages follow. Stop on totalPages, not on a short page.
Counts and rows can disagree on a few endpoints. If the numbers matter, rely on the rows you received.

Page through a full list#

Request pages until currentPage reaches totalPages. This example reads every domain with List Domains, which takes page and limit in the JSON body.
curl
JavaScript
Python
Keep paging within the Rate Limits: 5 requests per second and 200 per minute per key. For endpoints that return no total, such as Search Zapbox Emails, request the next page until a page comes back with fewer items than limit.
Related: Rate Limits, Errors.
Previous
Rate Limits
Next
Changelog
Built with