Documentation Index

Fetch the complete documentation index at: https://resend.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Overview

Several Resend API endpoints support cursor-based pagination to help you efficiently browse through large datasets. You can safely navigate lists with guaranteed stability, even if new objects are created or deleted while you’re still requesting pages. Paginated endpoints responses include:

• object: always set to list.
• has_more: indicates whether there are more elements available.
• data: the list of returned items.

You can navigate through the results using the following parameters:

• limit: the number of items to return per page.
• after: the cursor to use to get the next page of results.
• before: the cursor to use to get the previous page of results.

Use the id of objects as the cursor for pagination. The cursor itself is excluded from the results. For an example, see pagination strategies below.

Currently-supported endpoints

Existing list endpoints can optionally return paginated results:

• List Domains
• List API Keys
• List Broadcasts
• List Segments
• List Contacts
• List Receiving Emails
• List Receiving Email Attachments

Newer list endpoints always return paginated results:

• List Emails
• List Templates
• List Topics

Parameters

All paginated endpoints support the following query parameters:

The number of items to return per page. Default is 20, maximum is 100, and minimum is 1.

The cursor after which to start retrieving items. To get the next page, use the ID of the last item from the current page. This will return the page that starts after the object with this ID (excluding the passed ID itself).

The cursor before which to start retrieving items. To get the previous page, use the ID of the first item from the current page. This will return the page that ends before the object with this ID (excluding the passed ID itself).

Response Format

Paginated endpoints return responses in the following format:

{
  "object": "list",
  "has_more": true,
  "data": [
    /* Array of resources */
  ]
}

Always set to list for paginated responses.

Indicates whether there are more items available beyond the current page.

An array containing the actual resources for the current page.

Strategies

To paginate forward through results (newer to older items), use the after parameter with the ID of the last item from the current page:

Node.js

const resend = new Resend('re_xxxxxxxxx');

// First page
const { data: firstPage } = await resend.contacts.list({ limit: 50 });

// Second page (if has_more is true)
if (firstPage.has_more) {
  const lastId = firstPage.data[firstPage.data.length - 1].id;
  const { data: secondPage } = await resend.contacts.list({
    limit: 50,
    after: lastId,
  });
}

To paginate backward through results (older to newer items), use the before parameter with the ID of the first item from the current page (or the most recent ID you have in your system):

Node.js

const resend = new Resend('re_xxxxxxxxx');

// Start from a specific point and go backward
const page = await resend.contacts.list({
  limit: 50,
  before: 'some-contact-id',
});

if (page.data.has_more) {
  const firstId = page.data.data[0].id;
  const previousPage = await resend.contacts.list({
    limit: 50,
    before: firstId,
  });
}

Best Practices

Error Handling

Pagination requests may return the following validation errors:

Example error response:

{
  "name": "validation_error",
  "statusCode": 422,
  "message": "The pagination limit must be a number between 1 and 100. See https://resend.com/docs/pagination for more information."
}