An Agent Account grant addresses the same /v3/grants/{grant_id}/* endpoints as any other Nylas grant — you don’t need a separate client, SDK, or URL prefix. This page lists the endpoints and webhook triggers Agent Accounts currently support, plus the resources that only apply to Agent Accounts (Policies, Rules, Lists, and protocol-level access).
If you’ve built against connected grants before, the mental model is: same endpoints, same auth, same payloads — plus a handful of admin APIs and a couple of endpoints that aren’t available (called out below).
The Nylas CLI wraps provisioning with nylas agent account (create, list, get, delete) plus nylas agent status, nylas agent policy, and nylas agent rule; every other operation listed on this page is reachable through the CLI’s general nylas email, nylas calendar, and nylas contacts commands against the Agent Account grant, or directly through the REST API shown here.
Messages
Section titled “Messages”Read, send, update, and delete messages the same way you do for any other grant.
| Endpoint | What it does |
|---|---|
GET /v3/grants/{grant_id}/messages | List messages. Filter by thread_id, from, to, cc, bcc, subject, any_email, has_attachment, starred, unread, in (folder), received_after, received_before. |
GET /v3/grants/{grant_id}/messages/{message_id} | Fetch a single message, including body. Pass fields=raw_mime to get the raw MIME. |
PUT /v3/grants/{grant_id}/messages/{message_id} | Update starred, unread, answered, or folders on a message. |
DELETE /v3/grants/{grant_id}/messages/{message_id} | Soft-delete — moves the message to Trash. |
POST /v3/grants/{grant_id}/messages/send | Send outbound mail from the Agent Account. JSON body or multipart with attachments. |
PUT /v3/grants/{grant_id}/messages/clean | Extract clean display-ready content from up to 20 messages at a time. |
Threads
Section titled “Threads”Threads are how agents maintain conversation context across replies. When someone replies to a message the agent sent, Nylas groups it into the same thread using the In-Reply-To and References headers. The message.created webhook includes a thread_id you can look up here to get the full conversation history before deciding how to respond. See Email threading for agents for the full explanation.
| Endpoint | What it does |
|---|---|
GET /v3/grants/{grant_id}/threads | List threads across the mailbox. |
GET /v3/grants/{grant_id}/threads/{thread_id} | Fetch a single thread, including message summaries. |
PUT /v3/grants/{grant_id}/threads/{thread_id} | Update flags or folder on every message in the thread. |
DELETE /v3/grants/{grant_id}/threads/{thread_id} | Soft-delete — moves every message in the thread to Trash. |
Folders
Section titled “Folders”Agent Accounts auto-provision six system folders: inbox, sent, drafts, trash, junk, and archive. You can create custom folders alongside them.
| Endpoint | What it does |
|---|---|
GET /v3/grants/{grant_id}/folders | List all folders, system and custom. |
POST /v3/grants/{grant_id}/folders | Create a custom folder. System folder names are reserved. |
GET /v3/grants/{grant_id}/folders/{folder_id} | Fetch a single folder. |
PUT /v3/grants/{grant_id}/folders/{folder_id} | Rename a custom folder. System folders can’t be modified. |
DELETE /v3/grants/{grant_id}/folders/{folder_id} | Delete a custom folder. |
Drafts
Section titled “Drafts”Full CRUD is supported. The send action is a POST against an existing draft — there’s no separate “send draft” endpoint.
| Endpoint | What it does |
|---|---|
GET /v3/grants/{grant_id}/drafts | List drafts. |
POST /v3/grants/{grant_id}/drafts | Create a draft. Fires draft.created. |
GET /v3/grants/{grant_id}/drafts/{draft_id} | Fetch a single draft. |
PUT /v3/grants/{grant_id}/drafts/{draft_id} | Update draft body, recipients, attachments. Fires draft.updated. |
DELETE /v3/grants/{grant_id}/drafts/{draft_id} | Delete a draft. (No draft.deleted webhook fires.) |
POST /v3/grants/{grant_id}/drafts/{draft_id} | Send an existing draft. |
Attachments
Section titled “Attachments”| Endpoint | What it does |
|---|---|
GET /v3/grants/{grant_id}/attachments/{attachment_id} | Fetch attachment metadata. Pass message_id when required by the attachment. |
GET /v3/grants/{grant_id}/attachments/{attachment_id}/download | Stream the attachment bytes. |
Inbound attachment limits are enforced by your plan and the grant’s policy — tune limit_attachment_size_limit, limit_attachment_count_limit, and limit_attachment_allowed_types to fit your use case. Outbound attachments are limited by standard email message sizes.
Calendars
Section titled “Calendars”Every Agent Account comes with a primary calendar that’s provisioned automatically. You can create additional calendars up to your plan’s cap.
| Endpoint | What it does |
|---|---|
GET /v3/grants/{grant_id}/calendars | List every calendar on the account. |
POST /v3/grants/{grant_id}/calendars | Create an additional calendar. |
GET /v3/grants/{grant_id}/calendars/{calendar_id} | Fetch a single calendar. |
PUT /v3/grants/{grant_id}/calendars/{calendar_id} | Rename or update calendar metadata. |
DELETE /v3/grants/{grant_id}/calendars/{calendar_id} | Delete a calendar. The primary calendar can’t be deleted while other calendars exist. |
GET /v3/grants/{grant_id}/calendars/free-busy | Return free/busy blocks for the Agent Account’s primary calendar over a time range. |
Events
Section titled “Events”| Endpoint | What it does |
|---|---|
GET /v3/grants/{grant_id}/events | List events. Pass expand_recurring=true to materialize recurring instances. |
POST /v3/grants/{grant_id}/events | Create an event. Sends an ICS REQUEST to participants when notify_participants=true. |
GET /v3/grants/{grant_id}/events/{event_id} | Fetch a single event. |
PUT /v3/grants/{grant_id}/events/{event_id} | Update an event. Sends an ICS update to participants when the Agent Account is the organizer. |
DELETE /v3/grants/{grant_id}/events/{event_id} | Delete an event. Sends an ICS CANCEL when the Agent Account is the organizer. |
POST /v3/grants/{grant_id}/events/{event_id}/send-rsvp | RSVP to an invitation with yes, no, or maybe. Sends an ICS REPLY to every participant. |
Invitations arrive and are sent over standard iCalendar/ICS, so the Agent Account interoperates with Google Calendar, Microsoft 365, and Apple Calendar as a normal participant.
Contacts
Section titled “Contacts”| Endpoint | What it does |
|---|---|
GET /v3/grants/{grant_id}/contacts | List contacts. Filter by email, phone_number, or source. |
POST /v3/grants/{grant_id}/contacts | Create a contact. Fires contact.updated. |
GET /v3/grants/{grant_id}/contacts/{contact_id} | Fetch a single contact. |
PUT /v3/grants/{grant_id}/contacts/{contact_id} | Update a contact. |
DELETE /v3/grants/{grant_id}/contacts/{contact_id} | Delete a contact. Fires contact.deleted. |
Agent Accounts don’t support contact groups (/contacts/groups) — the resource isn’t implemented for this provider.
Webhooks
Section titled “Webhooks”Subscribe with POST /v3/webhooks — or with the CLI’s nylas webhook command family — and you’ll receive these triggers for Agent Account activity. Payload shapes match the existing webhook schemas.
| Trigger | What it fires on |
|---|---|
message.created | A new message arrives or is sent from the Agent Account. When a message body exceeds ~1 MB, the trigger name becomes message.created.truncated and the body is omitted. |
message.updated | A flag changes (unread, starred, answered), the message moves folder, or the message is deleted (moved to trash). |
message.transactional.bounced, .complaint, .delivered, .rejected | Deliverability signals for outbound mail sent from the Agent Account. |
event.created, event.updated, event.deleted | Calendar events created, updated, or deleted on an Agent Account calendar. |
contact.updated, contact.deleted | Contact records created, updated, or deleted. |
grant.created, grant.updated, grant.deleted, grant.expired | Lifecycle events emitted from the authentication service. Agent Accounts rarely expire because there’s no OAuth token to refresh. |
Agent-Account-only resources
Section titled “Agent-Account-only resources”These resources are specific to Agent Accounts. Connected grants from other providers don’t expose them.
| Resource | What it’s for |
|---|---|
| Policies | Bundle limits, spam detection, options, and a list of rule IDs. Apply one policy to many Agent Accounts via settings.policy_id. |
| Rules | Match inbound messages by from.address, from.domain, or from.tld and apply actions (block, mark_as_spam, assign_to_folder, mark_as_read, mark_as_starred, archive, trash). |
| Lists | Typed collections of domains, TLDs, or email addresses referenced by rules through the in_list operator. |
GET /v3/grants/{grant_id}/rule-evaluations | Audit which rules ran on recent inbound messages and what actions were applied. |
| IMAP and SMTP submission | Connect standard mail clients to an Agent Account using an app_password on the grant. |
See Policies, Rules, and Lists for how these fit together, and Mail client access for IMAP/SMTP setup.
Not currently supported
Section titled “Not currently supported”The following Nylas surfaces don’t apply to Agent Accounts:
- Smart Compose (
/messages/smart-compose) — the AI-drafting endpoint runs against connected OAuth grants only. - ExtractAI (
/consolidated-order,/consolidated-shipment,/consolidated-return) — not available. - Templates and Workflows (
/templates,/workflows) — not implemented for Agent Account grants. - Contact groups (
/contacts/groups) — not implemented for Agent Accounts; contacts CRUD still works. - Provider-specific search syntax (e.g., Gmail’s
search_query_native) — Agent Accounts run on Nylas-hosted infrastructure, so the standard Nylas query parameters are the only search surface. - Native message tracking on API sends —
message.openedandmessage.link_clickedaren’t currently emitted for messages sent directly throughPOST /messages/sendon an Agent Account.
If you need one of these for an Agent Account today, let us know — these decisions will change as the product moves out of beta.
Poll vs webhooks
Section titled “Poll vs webhooks”Both patterns are supported for inbound. Webhooks are recommended when you want near-real-time reactions (the grant-scoped triggers above fire within seconds of the event). Polling GET /messages on a cadence is a fine choice for batch workflows or periodic sync jobs.
If you’ve enabled IMAP access, IMAP IDLE gives mail clients push-style updates without a webhook subscription.
What’s next
Section titled “What’s next”- Agent Accounts quickstart for an end-to-end flow that exercises the core endpoints
- Provisioning and domains to create Agent Accounts and attach policies
- Policies, Rules, and Lists for admin configuration and the rule-evaluations audit trail
- Mail client access (IMAP & SMTP) to expose the mailbox to standard clients
- Webhook notifications for the complete payload schemas