{"slug": "every-endpoint-that-works-with-agent-accounts", "title": "Every Endpoint That Works With Agent Accounts", "summary": "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.", "body_md": "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`\n\nfolder, 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?\n\nFor 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/).\n\nAn Agent Account grant addresses `/v3/grants/{grant_id}/*`\n\nlike 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.\n\n**Messages** support the full lifecycle: list (with filters like `thread_id`\n\n, `from`\n\n, `subject`\n\n, `has_attachment`\n\n, `unread`\n\n, and `received_after`\n\n), fetch one (pass `fields=raw_mime`\n\nfor 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.\n\n**Threads** are how your agent keeps conversation context. Replies get grouped using `In-Reply-To`\n\nand `References`\n\nheaders, and the `message.created`\n\nwebhook includes a `thread_id`\n\nyou can look up to fetch the whole conversation before deciding how to respond. Threads also support bulk operations: `PUT /threads/{thread_id}`\n\nupdates flags or folder on *every* message in the thread at once, and `DELETE`\n\nsoft-deletes the whole conversation to Trash — useful when a triage agent resolves a ticket and wants to file the entire exchange in one call.\n\n**Folders** come pre-provisioned: every account starts with six system folders (`inbox`\n\n, `sent`\n\n, `drafts`\n\n, `trash`\n\n, `junk`\n\n, `archive`\n\n). You can create custom folders alongside them; system folder names are reserved and system folders can't be modified.\n\n**Drafts** get full CRUD, and the send action is a quirk worth knowing — there's no separate \"send draft\" route. You `POST`\n\nagainst the existing draft:\n\n```\n# Create a draft (fires draft.created)\ncurl --request POST \\\n  --url \"https://api.us.nylas.com/v3/grants/<GRANT_ID>/drafts\" \\\n  --header \"Authorization: Bearer <NYLAS_API_KEY>\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{ \"subject\": \"Re: your ticket\", \"to\": [{ \"email\": \"customer@example.com\" }] }'\n\n# Later: send that same draft\ncurl --request POST \\\n  --url \"https://api.us.nylas.com/v3/grants/<GRANT_ID>/drafts/<DRAFT_ID>\" \\\n  --header \"Authorization: Bearer <NYLAS_API_KEY>\"\n```\n\nThat 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`\n\n.\n\n**Attachments** support metadata fetch and byte streaming via `/attachments/{id}/download`\n\n. 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`\n\n, `limit_attachment_count_limit`\n\n, and `limit_attachment_allowed_types`\n\n. Outbound attachments are bounded by standard email message sizes.\n\nEvery 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.\n\nEvents cover list (with `expand_recurring=true`\n\nto materialize recurring instances), create, update, delete, and `send-rsvp`\n\nwith `yes`\n\n, `no`\n\n, or `maybe`\n\n. Everything travels over standard iCalendar — creates send an ICS `REQUEST`\n\n, deletes send a `CANCEL`\n\n, RSVPs send a `REPLY`\n\n— which is why Google Calendar, Microsoft 365, and Apple Calendar all treat the agent as a normal participant.\n\nContacts get full CRUD with filtering by `email`\n\n, `phone_number`\n\n, or `source`\n\n. One gap: contact *groups* aren't implemented for this provider.\n\nOn the webhook side, you subscribe once with `POST /v3/webhooks`\n\nand receive the standard grant-scoped triggers: `message.created`\n\n(which becomes `message.created.truncated`\n\nwith the body omitted when a message exceeds ~1 MB), `message.updated`\n\n, the deliverability trio (`send_success`\n\n, `send_failed`\n\n, `bounce_detected`\n\n), the three event triggers, contact changes, and grant lifecycle events. Payload shapes match the existing schemas, so existing webhook handlers keep working.\n\nTwo webhook details that don't follow the obvious pattern: deleting a draft fires *no* `draft.deleted`\n\ntrigger (creates and updates do fire `draft.created`\n\nand `draft.updated`\n\n), and `grant.expired`\n\nis mostly theoretical here — Agent Accounts rarely expire because there's no OAuth token to refresh.\n\nBack to the opening scenario. Here's the support agent's full loop expressed as actual calls:\n\n`message.created`\n\nwebhook fires, or `GET /messages?in=inbox&unread=true`\n\non a poll.`GET /threads/{thread_id}`\n\nusing the `thread_id`\n\nfrom the webhook payload; you get the conversation history with message summaries.`GET /attachments/{id}/download`\n\nwith the `message_id`\n\n, streaming the bytes straight to your parser.`PUT /messages/{message_id}`\n\nwith a `folders`\n\nvalue pointing at your custom `processed`\n\nfolder (created once with `POST /folders`\n\n).`POST /messages/send`\n\n, 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.\n\nFour 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`\n\nor `assign_to_folder`\n\n), **Lists** (typed allow/block collections referenced via `in_list`\n\n), and a per-grant `rule-evaluations`\n\naudit endpoint that answers \"why did this message get blocked?\". There's also IMAP and SMTP access if you set an `app_password`\n\non the grant — meaning a human can open the agent's mailbox in Thunderbird.\n\nThe honest list, straight from the docs:\n\n`search_query_native`\n\n— standard query parameters are the only search surface`message.opened`\n\nand `message.link_clicked`\n\naren'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.\n\nBoth work for inbound. Webhooks fire within seconds and suit real-time agents; polling `GET /messages`\n\non 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.\n\nBookmark 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.", "url": "https://wpnews.pro/news/every-endpoint-that-works-with-agent-accounts", "canonical_source": "https://dev.to/qasim157/every-endpoint-that-works-with-agent-accounts-4fp3", "published_at": "2026-06-15 14:59:21+00:00", "updated_at": "2026-06-15 15:06:48.139203+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents"], "entities": ["Nylas", "Agent Accounts", "Gmail", "Outlook"], "alternates": {"html": "https://wpnews.pro/news/every-endpoint-that-works-with-agent-accounts", "markdown": "https://wpnews.pro/news/every-endpoint-that-works-with-agent-accounts.md", "text": "https://wpnews.pro/news/every-endpoint-that-works-with-agent-accounts.txt", "jsonld": "https://wpnews.pro/news/every-endpoint-that-works-with-agent-accounts.jsonld"}}