Pagination

Every list endpoint returns a page envelope:

1
{
2
  "data": [ /* … up to `limit` items … */ ],
3
  "next_cursor": "eyJvIjoyNX0"
4
}

• data — the items in this page.
• next_cursor — pass this back as ?cursor= to fetch the next page. When it is null, you’ve reached the end.

Paging through results

Request the first page, then keep passing next_cursor back as cursor until it’s null:

$
# First page
$
curl "https://api.usglobalmail.com/v1/mails?limit=50" \
>
  -H "Authorization: Bearer $USGM_API_KEY"
$
$
# Next page
$
curl "https://api.usglobalmail.com/v1/mails?limit=50&cursor=eyJvIjoyNX0" \
>
  -H "Authorization: Bearer $USGM_API_KEY"

The SDKs handle this for you — list methods return an iterator that fetches pages transparently:

1
for await (const mail of usgm.mails.list({ limit: 50 })) {
2
  console.log(mail.id);
3
}

Limit

Notes