Every Endpoint That Works With Agent Accounts

#api #email #reference #agents

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.

Same routes, same payloads

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.

The mail surface

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

The calendar surface

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 and webhooks

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.

The triage agent, mapped

Back to the opening scenario. Here's the support agent's full loop expressed as actual calls:

Read incoming mail — message.created webhook fires, or GET /messages?in=inbox&unread=true on a poll.
Pull the thread for context — GET /threads/{thread_id} using the thread_id from the webhook payload; you get the conversation history with message summaries.
Download the invoice PDF — GET /attachments/{id}/download with the message_id, streaming the bytes straight to your parser.
File the message — PUT /messages/{message_id} with a folders value pointing at your custom processed folder (created once with POST /folders).
Send the reply — 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.

The admin-only extras

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.

What's missing

The honest list, straight from the docs:

Smart Compose — the AI-drafting endpoint runs against connected OAuth grants only
Templates and Workflows — not implemented
Contact groups — not implemented (plain contacts work)
Provider-native search like Gmail's search_query_native — standard query parameters are the only search surface
Open and click tracking — message.opened and message.link_clicked aren't emitted for direct API sends

None of these blocked the triage agent from the opening scenario, but if one blocks yours, the docs explicitly ask for feedback before general availability.

Poll or push?

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.