# Pagination



> Mailrith uses cursor pagination across list endpoints. This guide explains how to request the first page, continue with `next_cursor`, resume interrupted syncs, and reuse the same pagination pattern across subscribers, tags, custom fields, forms, and segments.



- Human page: https://mailrith.com/developers/pagination

- Markdown page: https://mailrith.com/developers/pagination.md

- Category: API Concepts

- Reading time: 6 min read

- Last updated: 2026-07-13

- Related keywords: Pagination, Pagination developer docs, API Concepts, API Concepts developer docs, Mailrith developer docs, Mailrith public API, Use Cursor Pagination, Apply the Same Pattern Across Resources, Subscribers API, Tags API, Segments API



## AI Agent Notes

- Use this page as implementation guidance, then validate exact endpoint fields against the OpenAPI document.

- Keep API keys server-side and workspace-scoped unless a guide explicitly says otherwise.

- Do not invent privacy, consent, or lawful-basis evidence. Send only fields that appear in the OpenAPI schema for the endpoint you are using.



## What this guide covers

Page through large list endpoints safely with cursors, saved progress, and reusable sync loops.



## Use Cursor Pagination

Mailrith uses cursor pagination for list endpoints. Each API response gives your integration the cursor to use for the next page, so your integration does not need to guess a page number.

Cursor pagination is important when records change while your integration is reading a workspace. Subscribers, tags, forms, landing pages, and segments can be added during a sync. The cursor gives your integration a stable next request even when the total record count changes.

To request the first page, omit `starting_after`. If the API response sets `has_more` to true, copy `next_cursor` into the next request as `starting_after`. Keep requesting pages until `has_more` is false.

1. Send the first list request with a `limit` and without a `starting_after` value.
2. Process every item in the returned `data` array before requesting the next page.
3. Read the `pagination` object in the API response.
4. If `has_more` is false, stop the pagination loop.
5. If `has_more` is true, store `next_cursor` and send the next request with `starting_after=<next_cursor>`.
6. After each page is fully processed, write your progress so a scheduled sync can resume safely.
7. Use the same pagination loop for subscribers, tags, custom fields, forms, landing pages, and segments.

- Use `limit` to set how many records Mailrith should return in one API response.
- Use `starting_after` only after Mailrith returns a `next_cursor` from the previous page.
- Do not invent cursor values, count pages, or assume that a record's database order will never change.
- For scheduled syncs, store the last cursor after you successfully process its page so a failed job can resume cleanly.
- For one-time exports or migrations, keep requesting pages until `has_more` is false.

**Paginated List Request**

```bash
curl "https://api.mailrith.com/v1/subscribers?limit=50&starting_after=subscriber_123" \
  -H "Authorization: Bearer mrk_example_secret_key"
```

**Paginated Response**

```json
{
  "data": [],
  "pagination": {
    "has_more": true,
    "next_cursor": "subscriber_456"
  }
}
```

## Apply the Same Pattern Across Resources

List-style resources use the same pagination pattern. After your integration handles one list endpoint correctly, it can usually reuse the same loop for other resources.

Keep the loop simple: send a request, process every item in `data`, save the next cursor, and stop only when Mailrith says there are no more records.

Do not load an entire workspace into memory when the workspace may contain a large subscriber list. Process each page as Mailrith returns it, write progress to durable storage, and then request the next cursor.

- subscribers are usually the largest list, so process subscriber records page by page.
- Tags, custom fields, forms, landing pages, and segments may be smaller, but the same cursor loop keeps the integration consistent.
- If a job stops after processing a page, resume from the cursor after the last fully processed page.
- If you need a fresh full sync, start again without `starting_after` instead of reusing an old cursor from a different run.

Related OpenAPI operation groups:
- Subscribers
- Tags
- Custom Fields
- Forms
- Segments



## Related Guides

- [Subscribers API](https://mailrith.com/developers/subscribers.md): The subscribers resource is the main way integrations write Subscriber data in `v1`. This guide explains when to list subscribers, when to upsert subscribers, how Mailrith chooses the workspace, what to include in an upsert body, and when to use async imports instead of many single requests.

- [Tags API](https://mailrith.com/developers/tags.md): The tags API gives integrations a lightweight way to manage subscriber labels. This guide explains when to use tags, when to use custom fields instead, how to list or create tags, and how to name tags so workspace users understand each label.

- [Segments API](https://mailrith.com/developers/segments.md): The segments API supports saved segment definitions, imported subscriber rules, and previews for unsaved logic. This guide explains how segments behave, when to save segments, and why preview is the safest step before using complex subscriber rules.