Paginate email messages with durable processing checkpoints

A page is a window, not an inventory

Email list endpoints return a bounded collection. The default limit is 50 and the maximum is 100, so a single successful response does not prove you have processed an entire inbox. Use GET /v0/emails/inboxes/:inbox_id/emails with limit and page_token. The envelope includes emails, count, limit and, when another page exists, next_page_token. Count describes the returned page; it is not a promise about the size of the whole mailbox. An empty page also needs to be interpreted alongside your filters and the credential’s label visibility.

Keep the query stable while walking

Treat next_page_token as opaque and send it back as page_token. Preserve the same inbox, limit, ordering and filters throughout one traversal. Changing from newest-first to ascending ordering halfway through makes the checkpoint ambiguous. Use URLSearchParams or equivalent URL encoding instead of concatenating a token into a query string. The current implementation uses offset-style pagination internally, so concurrent arrivals or deletions can shift page boundaries. Your worker must tolerate duplicate observations and should reconcile a bounded overlapping time window rather than claiming a cursor is a permanent snapshot.

curl --fail-with-body --get \
  "https://api.lupin.sh/v0/emails/inboxes/$INBOX_ID/emails" \
  -H "Authorization: Bearer $LUPIN_API_KEY" \
  --data-urlencode "limit=50" \
  --data-urlencode "page_token=$NEXT_PAGE_TOKEN"

Checkpoint after durable work

Save a message_id processing record before or atomically with the result of your local classification. Advance the page checkpoint only after the page’s required work is durably represented. If the process crashes after five messages, it can reread the same page and skip those already completed. This is different from advancing the cursor first and hoping every message finished. Include the processing revision in your local key when intentionally rerunning an improved classifier; otherwise a deduplication record from the old classifier can hide the work you actually meant to repeat.

Bound load and retries

A small page size can reduce response size and model context even if the endpoint supports larger pages. Read message details only for candidates that need deeper analysis. Honor Retry-After when the API returns 429 and preserve the same checkpoint across retryable network failures. A 401 requires credential repair, while a 403 requires permission review; neither becomes valid by increasing retry frequency. Track pages visited, unique message IDs and work completed separately so a repeated page does not inflate your success count or make a stuck cursor look like useful progress.

Reconcile with events and timestamps

Webhooks can wake a worker promptly, while periodic pagination checks for gaps. Neither channel should directly create duplicate external actions. Use the same local message identity when a webhook and a backfill discover the same email. For historical processing, select an explicit before boundary and document the ordering; for continuous processing, retain a recent overlap and deduplicate. The next useful check is to insert a new message between two fixture pages and verify your worker repeats observations safely. Do that locally, without sending live mail merely to manufacture pagination traffic.

Do not infer a global total

If a page contains count 50 and a next_page_token, report fifty observed messages on that page rather than fifty messages in the inbox. If a later page fails, retain the partial completion explicitly. This small reporting distinction prevents a model from presenting an interrupted backfill as a complete mailbox inventory and helps operators resume at the correct checkpoint.

Sources & verification

Reviewed against checked-in Lupin API handlers and documentation. Example requests were not executed against live providers.

• Lupin conventions ↗Checked 2026-11-05
• Lupin messages ↗Checked 2026-11-05

Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.