Pagination

List endpoints that can grow large are paginated with cursors. Results are always sorted newest first.

#Parameters

Use either after or before, not both.

#Response

{
  "object": "list",
  "data": [
    { "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c", "...": "..." },
    { "id": "9a2c5f10-7b1e-4d0f-8a6b-2f4c1e9d3b77", "...": "..." }
  ],
  "has_more": true
}

has_more is true when more items exist in the direction you are paging.

#Walk through a list

Request the first page, then pass the ID of the last item as after to get the next one:

curl "https://api.usend.et/emails?limit=100" \
  -H "Authorization: Bearer us_123456789"

curl "https://api.usend.et/emails?limit=100&after=9a2c5f10-7b1e-4d0f-8a6b-2f4c1e9d3b77" \
  -H "Authorization: Bearer us_123456789"

To go back, pass the ID of the first item of the current page as before.

async function* allEmails() {
  let after;
  while (true) {
    const { data: page, error } = await usend.emails.list({ limit: 100, after });
    if (error) throw new Error(error.message);
    yield* page.data;
    if (!page.has_more) return;
    after = page.data[page.data.length - 1].id;
  }
}

def all_emails():
    params = {"limit": 100}
    while True:
        page = usend.emails.list(**params)
        yield from page["data"]
        if not page["has_more"]:
            return
        params["after"] = page["data"][-1]["id"]

#Paginated endpoints

• GET /emails
• GET /inbound/emails
• GET /templates
• GET /contacts
• GET /audiences/{audience_id}/contacts
• GET /suppressions
• GET /webhooks/{id}/deliveries

Other lists (domains, API keys, audiences, segments, broadcasts, webhooks) return all items at once. An invalid limit, after or before fails with 422 validation_error.