Every Endpoint That Works With Agent Accounts

Nylas's Agent Accounts (beta) support nearly all API endpoints used for connected Gmail or Outlook grants, including messages, threads, folders, drafts, attachments, calendars, and events. The same routes, authentication, and payloads apply, with a few admin-only resources and gaps. This enables building support triage agents that can read, send, and manage emails and calendar events through a unified API.

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 https://developer.nylas.com/docs/v3/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 https://developer.nylas.com/docs/v3/agent-accounts/supported-endpoints/ . 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: Create a draft fires draft.created 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" } }' Later: send that same draft 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 https://developer.nylas.com/docs/v3/agent-accounts/policies-rules-lists/ — 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 surface message.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 https://developer.nylas.com/docs/v3/agent-accounts/supported-endpoints/ — 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.