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.
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 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, 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.