# Listing and Paginating an Agent's Messages > Source: > Published: 2026-06-16 11:06:23+00:00 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//messages?limit=5" \ --header "Authorization: Bearer " ``` 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//messages/" \ --header "Authorization: Bearer " ``` 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//messages?in=inbox&unread=true&received_after=1744387200&limit=50" \ --header "Authorization: Bearer " ``` `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//messages?limit=50&page_token=" \ --header "Authorization: Bearer " ``` 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//threads/" \ --header "Authorization: Bearer " ``` 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=` 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.