API Reference

Pagination

How cursor-based pagination works across MailBlastr list endpoints: limit, after, before, and has_more.

Several MailBlastr list endpoints support cursor-based pagination so you can browse large datasets reliably. Because the cursor is an object id rather than an offset, paging stays stable even when records are created or deleted while you are still requesting pages.

Response shape

Every paginated response is a list object with these fields:

objectstringoptional

Always list for a paginated response.

has_morebooleanoptional

Whether more items exist beyond the current page.

dataarrayoptional

The items for the current page.

{
  "object": "list",
  "has_more": true,
  "data": [
    { "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c", "subject": "Hello World" },
    { "id": "3a9f8c2b-1e5d-4f8a-9c7b-2d6e5f8a9c7b", "subject": "Welcome aboard" }
  ]
}

Parameters

Navigate the results with these query parameters. Use an object's id as the cursor — the cursor itself is always excluded from the returned page.

limitnumberoptional

Items to return per page. Default 20, maximum 100, minimum 1.

afterstringoptional

Return the page that starts after the object with this id (the next page). Use the id of the last item on the current page.

beforestringoptional

Return the page that ends before the object with this id (the previous page). Use the id of the first item on the current page.

You can use either after or before, but not both in the same request.

Optional vs. always-paginated

For older list endpoints the limit parameter is optional — omit it and all items are returned in a single response:

List Received Emails — GET /emails/receiving
List Received Attachments — GET /emails/receiving/:id/attachments
List Attachments — GET /emails/:id/attachments

Newer list endpoints are always paginated (they return at most limit, default 20, items per page):

List Sent Emails — GET /emails
List Logs — GET /logs

Forward pagination

To page forward (newer to older), take the id of the last item on the current page and pass it as after. Stop when has_more is false.

# First page
curl -X GET 'https://api.mailblastr.com/emails?limit=50' \
  -H 'Authorization: Bearer mb_xxxxxxxxx'

# Next page — pass the id of the last item from the previous page
curl -X GET 'https://api.mailblastr.com/emails?limit=50&after=LAST_ID_FROM_PREVIOUS_PAGE' \
  -H 'Authorization: Bearer mb_xxxxxxxxx'

Backward pagination

To page backward (older to newer), take the id of the first item on the current page and pass it as before.

curl -X GET 'https://api.mailblastr.com/emails?limit=50&before=FIRST_ID_FROM_CURRENT_PAGE' \
  -H 'Authorization: Bearer mb_xxxxxxxxx'

Best practices

Always check has_more before fetching another page — it tells you when you have reached the end.
Pick a limit that fits your workload: small pages for interactive UIs, larger pages (up to 100) for bulk processing.
Mind rate limits when paging through large datasets — add backoff between pages if needed.

Errors

Pagination requests return validation_error (422) if the cursor format is invalid, if limit is outside 1–100, or if both before and after are supplied. See the error reference.