Listing and Paginating an Agent's Messages

Every email agent demo shows the send path. Then you ship one, and it turns out 80% of your code is the read path: pulling messages out of the mailbox, filtering down to the ones that matter, and walking pages of results without dropping anything. Get this wrong and your agent either reprocesses the same 50 messages forever or silently misses the one email it was built to catch.

Here's how the read path works for a Nylas Agent Account — a hosted mailbox your app owns outright (currently in beta). The nice part: an Agent Account is just a grant, so the messages endpoint is the exact same one you'd use for a connected Gmail or Outlook account.

The basic list call

One endpoint does the listing: GET /v3/grants/{grant_id}/messages. Messages come back in reverse chronological order — newest first.

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages?limit=5" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

By default you get the 50 most recent messages. The limit parameter is configurable up to a max of 200 per request. For an agent loop, smaller is usually better — you're typically reacting to recent activity, not rebuilding an archive.

The list response carries summary fields. When you need the full body of a specific message (and for anything you're feeding to an LLM, you do), fetch it individually:

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages/<MESSAGE_ID>" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

Pass fields=raw_mime on that call if you want the raw MIME instead of the parsed object — useful when your pipeline does its own parsing.

Filtering: don't fetch what you'll throw away

The list endpoint takes a generous set of query filters: thread_id, from, to, cc, bcc, subject, any_email, has_attachment, starred, unread, in (folder), received_after, and received_before.

Two of these do most of the work in agent code:

• in scopes the query to a folder. Agent Accounts auto-provision six system folders — inbox, sent, drafts, trash, junk, and archive — plus any custom folders you create. An agent that only cares about new inbound mail should query in=inbox and never waste a token on the junk folder.
• received_after turns the endpoint into an incremental sync. Store the timestamp of your last run, pass it on the next one, and you only see what's new.

Combine them and a polling agent gets tight, cheap queries:

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages?in=inbox&unread=true&received_after=1744387200&limit=50" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

any_email deserves a mention too — it matches an address across from, to, cc, and bcc in one shot, which beats running four separate queries when you want everything involving a particular contact.

Pagination: cursors, not offsets

When more results exist than your limit, the response includes a next_cursor. Pass it back as the page_token query parameter to get the next page:

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages?limit=50&page_token=<NEXT_CURSOR>" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

Loop until next_cursor is null or absent — that's the last page. The cursor model means you won't get the duplicated-or-skipped rows that offset pagination produces when new mail arrives mid-walk, which for an active mailbox is constantly.

A practical pattern for batch agents: paginate with limit=200 (the max) to minimize round trips, but keep your per-message processing idempotent anyway. Pagination guarantees are about the walk, not about your handler running exactly once.

Threads: the other read path

Messages are the raw feed; threads are the conversation view. When someone replies to mail your agent sent, Nylas groups the reply into the same thread using the In-Reply-To and References headers, and the message.created webhook payload carries a thread_id. Before your agent decides how to respond, pull the whole conversation:

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/threads/<THREAD_ID>" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

The thread object includes message summaries for every turn, which is usually exactly the context window you want to hand an LLM — the conversation so far, in order, without you maintaining a separate state store. PUT /threads/{thread_id} is also handy on the write-back side: it updates flags or moves the folder for every message in the thread in one call, so "this conversation is handled" is a single request instead of N.

Should you even be polling?

Listing is the right tool for batch workflows — a nightly digest, a backfill, a periodic sync job. For reactive agents, message.created webhooks are the better default: grant-scoped triggers fire within seconds of a message arriving, and you skip the whole "how often do we poll" question.

The two compose well, though. A common production setup is webhooks for the hot path plus a received_after polling sweep every few minutes as a safety net for anything missed during a deploy or an outage. The same list endpoint powers both.

One more read-path tool worth knowing: PUT /v3/grants/{grant_id}/messages/clean extracts clean, display-ready content from up to 20 messages at a time. If you're stuffing email bodies into an LLM prompt, stripping the quoted-reply pyramids and signature noise first saves real money.

A minimal read loop

Putting it together, the skeleton of a polling read path looks like:

1. Query in=inbox&unread=true&received_after=<last_run> with limit=50.
2. Page through with page_token until next_cursor disappears.
3. Fetch full bodies for the messages you'll act on.
4. Mark them read with PUT /messages/{id} so the next sweep skips them.
5. Persist the new received_after watermark.

Step 4 matters more than it looks — using the unread flag as your processed-marker keeps state in the mailbox itself, so a crashed worker picks up exactly where it left off. The same PUT /messages/{id} endpoint also updates starred, answered, and folders, so you can move processed mail to a custom processed folder instead if you'd rather keep unread semantics for humans supervising the box.

Gotchas worth knowing before you ship

A few read-path behaviors that surprise people the first time:

• Big bodies truncate the webhook, not the API. When a message body exceeds roughly 1 MB, the webhook trigger arrives as message.created.truncated with the body omitted. Your handler should treat the webhook as a notification and fetch the full message by ID — which works regardless of size — rather than trusting the payload to carry the body.
• No provider-native search syntax. Agent Accounts run on Nylas-hosted infrastructure, so Gmail-style search_query_native queries aren't available. The standard query parameters listed above are the whole search surface — design your filters around them.
• DELETE is a soft delete. Deleting a message moves it to the trash folder; it doesn't vanish. If your agent "cleans up" processed mail with deletes, remember those messages still show up in a trash-scoped query — and still count until retention expires.
• Flag changes fire message.updated. If you subscribe to both message.created and message.updated, your own mark-as-read writes from step 4 will echo back as webhook events. Filter those out or you'll build an accidental feedback loop.

The full endpoint matrix — every filter, plus threads, folders, and drafts — is on the supported endpoints page, and the quickstart gets you a live mailbox to test against in a few minutes.

What's your read-path poison: webhooks with a polling fallback, or pure polling with a tight watermark? I'd genuinely like to hear what's held up in production for you.