Listing and Paginating an Agent's Messages

Nylas details the read path for its Agent Account mailboxes, explaining how to list, filter, and paginate messages using the /v3/grants/{grant_id}/messages endpoint. The approach uses cursor-based pagination to avoid duplicate or skipped rows, and supports filters like inbox, unread, and received_after for efficient agent polling.

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 https://developer.nylas.com/docs/v3/agent-accounts/ — 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. 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. 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 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 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. 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. 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. Listing is the right tool for batch workflows — a nightly digest, a backfill, a periodic sync job. For reactive agents, message.created webhooks https://developer.nylas.com/docs/v3/getting-started/agent-accounts/ 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. Putting it together, the skeleton of a polling read path looks like: in=inbox&unread=true&received after=<last run with limit=50 . page token until next cursor disappears. PUT /messages/{id} so the next sweep skips them. 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. A few read-path behaviors that surprise people the first time: 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. 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. 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. message.updated . 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 https://developer.nylas.com/docs/v3/agent-accounts/supported-endpoints/ , and the quickstart https://developer.nylas.com/docs/v3/getting-started/agent-accounts/ 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.