Say you're building a support triage agent. It needs to read incoming mail, pull the full thread for context, download an invoice PDF, file the message in a processed
folder, and send a reply. That's five different API surfaces — and the first question you'll ask about any hosted-mailbox product is: which of them actually work?
For Nylas Agent Accounts (currently in beta), the answer is: nearly all of them, and through the exact same routes you'd use for a connected Gmail or Outlook grant. Here's the full tour, based on the supported endpoints reference.
An Agent Account grant addresses /v3/grants/{grant_id}/*
like any other grant. No separate client, no SDK fork, no URL prefix. If you've built against connected accounts, the mental model is: same endpoints, same auth, same payloads — plus a few admin-only resources and a couple of gaps I'll flag at the end.
Messages support the full lifecycle: list (with filters like thread_id
, from
, subject
, has_attachment
, unread
, and received_after
), fetch one (pass fields=raw_mime
for raw MIME), update flags and folders, soft-delete to Trash, and send. There's also a bulk-clean endpoint that extracts display-ready content from up to 20 messages per call — handy for feeding clean text to an LLM.
Threads are how your agent keeps conversation context. Replies get grouped using In-Reply-To
and References
headers, and the message.created
webhook includes a thread_id
you can look up to fetch the whole conversation before deciding how to respond. Threads also support bulk operations: PUT /threads/{thread_id}
updates flags or folder on every message in the thread at once, and DELETE
soft-deletes the whole conversation to Trash — useful when a triage agent resolves a ticket and wants to file the entire exchange in one call.
Folders come pre-provisioned: every account starts with six system folders (inbox
, sent
, drafts
, trash
, junk
, archive
). You can create custom folders alongside them; system folder names are reserved and system folders can't be modified.
Drafts get full CRUD, and the send action is a quirk worth knowing — there's no separate "send draft" route. You POST
against the existing draft:
curl --request POST \
--url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/drafts" \
--header "Authorization: Bearer <NYLAS_API_KEY>" \
--header "Content-Type: application/json" \
--data '{ "subject": "Re: your ticket", "to": [{ "email": "customer@example.com" }] }'
curl --request POST \
--url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/drafts/<DRAFT_ID>" \
--header "Authorization: Bearer <NYLAS_API_KEY>"
That create/review/send split is a nice fit for human-in-the-loop agents: the LLM drafts, a person approves, your code fires the second POST
.
Attachments support metadata fetch and byte streaming via /attachments/{id}/download
. Inbound size, count, and type limits come from your plan and the grant's policy — the relevant policy fields are limit_attachment_size_limit
, limit_attachment_count_limit
, and limit_attachment_allowed_types
. Outbound attachments are bounded by standard email message sizes.
Every account gets a primary calendar automatically, and you can create more up to your plan's cap. Calendars support list, create, fetch, update, and delete (the primary can't be deleted while others exist), plus a free/busy query for availability checks.
Events cover list (with expand_recurring=true
to materialize recurring instances), create, update, delete, and send-rsvp
with yes
, no
, or maybe
. Everything travels over standard iCalendar — creates send an ICS REQUEST
, deletes send a CANCEL
, RSVPs send a REPLY
— which is why Google Calendar, Microsoft 365, and Apple Calendar all treat the agent as a normal participant.
Contacts get full CRUD with filtering by email
, phone_number
, or source
. One gap: contact groups aren't implemented for this provider.
On the webhook side, you subscribe once with POST /v3/webhooks
and receive the standard grant-scoped triggers: message.created
(which becomes message.created.truncated
with the body omitted when a message exceeds ~1 MB), message.updated
, the deliverability trio (send_success
, send_failed
, bounce_detected
), the three event triggers, contact changes, and grant lifecycle events. Payload shapes match the existing schemas, so existing webhook handlers keep working.
Two webhook details that don't follow the obvious pattern: deleting a draft fires no draft.deleted
trigger (creates and updates do fire draft.created
and draft.updated
), and grant.expired
is mostly theoretical here — Agent Accounts rarely expire because there's no OAuth token to refresh.
Back to the opening scenario. Here's the support agent's full loop expressed as actual calls:
message.created
webhook fires, or GET /messages?in=inbox&unread=true
on a poll.GET /threads/{thread_id}
using the thread_id
from the webhook payload; you get the conversation history with message summaries.GET /attachments/{id}/download
with the message_id
, streaming the bytes straight to your parser.PUT /messages/{message_id}
with a folders
value pointing at your custom processed
folder (created once with POST /folders
).POST /messages/send
, or the draft-then-send pair if a human approves first.Five surfaces, one grant ID, zero provider-specific code. The same loop works unchanged if you later point it at a connected Gmail grant — which is the real payoff of reusing the grant abstraction.
Four resources exist only for these accounts: Policies (bundled limits and spam detection, attached to a workspace), Rules (match inbound or outbound mail and apply actions like block
or assign_to_folder
), Lists (typed allow/block collections referenced via in_list
), and a per-grant rule-evaluations
audit endpoint that answers "why did this message get blocked?". There's also IMAP and SMTP access if you set an app_password
on the grant — meaning a human can open the agent's mailbox in Thunderbird.
The honest list, straight from the docs:
search_query_native
— standard query parameters are the only search surfacemessage.opened
and message.link_clicked
aren't emitted for direct API sendsNone of these blocked the triage agent from the opening scenario, but if one blocks yours, the docs explicitly ask for feedback before general availability.
Both work for inbound. Webhooks fire within seconds and suit real-time agents; polling GET /messages
on a cadence is fine for batch jobs. And if IMAP access is enabled, IMAP IDLE gives mail clients push-style updates with no webhook subscription at all.
Bookmark the supported endpoints page — it's the single table I kept returning to while building. Which gap would block your use case? The not-supported list is the part most likely to change, so it's worth saying out loud.