# Supported endpoints for Agent Accounts

Source: https://developer.nylas.com/docs/v3/agent-accounts/supported-endpoints/

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](/docs/v3/getting-started/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.

> **Info:** 
> **New to Agent Accounts?** Start with the [Agent Accounts quickstart](/docs/v3/getting-started/agent-accounts/) to create your first account, or see [What are Agent Accounts](/docs/v3/agent-accounts/) for the product overview.

## 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`](/docs/reference/api/messages/get-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}`](/docs/reference/api/messages/get-messages-id/) | Fetch a single message, including body. Pass `fields=raw_mime` to get the raw MIME. |
| [`PUT /v3/grants/{grant_id}/messages/{message_id}`](/docs/reference/api/messages/put-messages-id/) | Update `starred`, `unread`, `answered`, or `folders` on a message. |
| [`DELETE /v3/grants/{grant_id}/messages/{message_id}`](/docs/reference/api/messages/delete-message/) | Soft-delete — moves the message to Trash. |
| [`POST /v3/grants/{grant_id}/messages/send`](/docs/reference/api/messages/send-message/) | Send outbound mail from the Agent Account. JSON body or multipart with attachments. If you omit the `from` field, Nylas defaults it to the Agent Account's own email address and name. |
| [`PUT /v3/grants/{grant_id}/messages/clean`](/docs/reference/api/messages/clean-messages/) | Extract clean display-ready content from up to 20 messages at a time. |

## 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](/docs/v3/agent-accounts/email-threading/) for the full explanation.

| Endpoint | What it does |
| --- | --- |
| [`GET /v3/grants/{grant_id}/threads`](/docs/reference/api/threads/get-threads/) | List threads across the mailbox. |
| [`GET /v3/grants/{grant_id}/threads/{thread_id}`](/docs/reference/api/threads/get-threads-id/) | Fetch a single thread, including message summaries. |
| [`PUT /v3/grants/{grant_id}/threads/{thread_id}`](/docs/reference/api/threads/put-threads-id/) | Update flags or folder on every message in the thread. |
| [`DELETE /v3/grants/{grant_id}/threads/{thread_id}`](/docs/reference/api/threads/delete-threads-id/) | Soft-delete — moves every message in the thread to Trash. |

## 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`](/docs/reference/api/folders/get-folder/) | List all folders, system and custom. |
| [`POST /v3/grants/{grant_id}/folders`](/docs/reference/api/folders/post-folder/) | Create a custom folder. System folder names are reserved. |
| [`GET /v3/grants/{grant_id}/folders/{folder_id}`](/docs/reference/api/folders/get-folders-id/) | Fetch a single folder. |
| [`PUT /v3/grants/{grant_id}/folders/{folder_id}`](/docs/reference/api/folders/put-folders-id/) | Rename a custom folder. System folders can't be modified. |
| [`DELETE /v3/grants/{grant_id}/folders/{folder_id}`](/docs/reference/api/folders/delete-folders-id/) | Delete a custom folder. |

## 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`](/docs/reference/api/drafts/get-drafts/) | List drafts. |
| [`POST /v3/grants/{grant_id}/drafts`](/docs/reference/api/drafts/post-draft/) | Create a draft. |
| [`GET /v3/grants/{grant_id}/drafts/{draft_id}`](/docs/reference/api/drafts/get-draft-id/) | Fetch a single draft. |
| [`PUT /v3/grants/{grant_id}/drafts/{draft_id}`](/docs/reference/api/drafts/put-drafts-id/) | Update draft body, recipients, attachments. |
| [`DELETE /v3/grants/{grant_id}/drafts/{draft_id}`](/docs/reference/api/drafts/delete-drafts-id/) | Delete a draft. |
| [`POST /v3/grants/{grant_id}/drafts/{draft_id}`](/docs/reference/api/drafts/send-draft-id/) | Send an existing draft. |

Sending a draft doesn't emit open or click tracking: [`message.opened`](/docs/reference/notifications/message-tracking/message-opened/) and [`message.link_clicked`](/docs/reference/notifications/message-tracking/message-link_clicked/) don't fire for messages sent through the drafts endpoint. To track opens and clicks, send directly with [`POST /v3/grants/{grant_id}/messages/send`](/docs/reference/api/messages/send-message/) and set `tracking_options`.

## Attachments

| Endpoint | What it does |
| --- | --- |
| [`GET /v3/grants/{grant_id}/attachments/{attachment_id}`](/docs/reference/api/attachments/get-attachments-id/) | Fetch attachment metadata. Pass `message_id` when required by the attachment. |
| [`GET /v3/grants/{grant_id}/attachments/{attachment_id}/download`](/docs/reference/api/attachments/get-attachments-id-download/) | Stream the attachment bytes. |

Inbound attachment limits are enforced by your plan and the grant's [policy](/docs/v3/agent-accounts/policies-rules-lists/) — 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

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`](/docs/reference/api/calendar/get-all-calendars/) | List every calendar on the account. |
| [`POST /v3/grants/{grant_id}/calendars`](/docs/reference/api/calendar/create-calendar/) | Create an additional calendar. |
| [`GET /v3/grants/{grant_id}/calendars/{calendar_id}`](/docs/reference/api/calendar/get-calendars-id/) | Fetch a single calendar. |
| [`PUT /v3/grants/{grant_id}/calendars/{calendar_id}`](/docs/reference/api/calendar/put-calendars-id/) | Rename or update calendar metadata. |
| [`DELETE /v3/grants/{grant_id}/calendars/{calendar_id}`](/docs/reference/api/calendar/delete-calendars-id/) | Delete a calendar. The primary calendar can't be deleted while other calendars exist. |
| [`POST /v3/grants/{grant_id}/calendars/free-busy`](/docs/reference/api/calendar/post-calendars-free-busy/) | Return free/busy blocks for the Agent Account's primary calendar over a time range. |
| [`POST /v3/grants/{grant_id}/calendars/availability`](/docs/reference/api/calendar/post-availability/) | Return availability across the account's calendars over a time window. |

## Events

| Endpoint | What it does |
| --- | --- |
| [`GET /v3/grants/{grant_id}/events`](/docs/reference/api/events/get-all-events/) | List events. Pass `expand_recurring=true` to materialize recurring instances. |
| [`GET /v3/grants/{grant_id}/events/import`](/docs/reference/api/events/import-events/) | Import and list events across the account's calendars over a time range. |
| [`POST /v3/grants/{grant_id}/events`](/docs/reference/api/events/create-event/) | Create an event. Sends an ICS `REQUEST` to participants when `notify_participants=true`. |
| [`GET /v3/grants/{grant_id}/events/{event_id}`](/docs/reference/api/events/get-events-id/) | Fetch a single event. |
| [`PUT /v3/grants/{grant_id}/events/{event_id}`](/docs/reference/api/events/put-events-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}`](/docs/reference/api/events/delete-events-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`](/docs/reference/api/events/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

| Endpoint | What it does |
| --- | --- |
| [`GET /v3/grants/{grant_id}/contacts`](/docs/reference/api/contacts/list-contact/) | List contacts. Filter by `email`, `phone_number`, or `source`. |
| [`POST /v3/grants/{grant_id}/contacts`](/docs/reference/api/contacts/post-contact/) | Create a contact. Fires `contact.updated`. |
| [`GET /v3/grants/{grant_id}/contacts/{contact_id}`](/docs/reference/api/contacts/get-contact/) | Fetch a single contact. |
| [`PUT /v3/grants/{grant_id}/contacts/{contact_id}`](/docs/reference/api/contacts/put-contact/) | Update a contact. |
| [`DELETE /v3/grants/{grant_id}/contacts/{contact_id}`](/docs/reference/api/contacts/delete-contact/) | Delete a contact. Fires `contact.deleted`. |

Agent Accounts don't support contact groups (`/contacts/groups`) — the resource isn't implemented for this provider.

## Webhooks

Subscribe with [`POST /v3/webhooks`](/docs/reference/api/webhook-notifications/post-webhook-destinations/) — 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](/docs/reference/notifications/).

| Trigger | What it fires on |
| --- | --- |
| [`message.created`](/docs/reference/notifications/messages/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`](/docs/reference/notifications/messages/message-updated/) | A flag changes (`unread`, `starred`, `answered`), the message moves folder, or the message is deleted (moved to trash). When the message body exceeds ~1 MB, the trigger name becomes `message.updated.truncated` and the body is omitted. |
| [`folder.created`](/docs/reference/notifications/folders/folder-created/), [`folder.updated`](/docs/reference/notifications/folders/folder-updated/), [`folder.deleted`](/docs/reference/notifications/folders/folder-deleted/) | A folder is created, renamed or otherwise updated, or deleted. |
| [`message.delivered`](/docs/reference/notifications/agent-accounts/message-delivered/), [`message.bounced`](/docs/reference/notifications/agent-accounts/message-bounced/), [`message.complaint`](/docs/reference/notifications/agent-accounts/message-complaint/), [`message.rejected`](/docs/reference/notifications/agent-accounts/message-rejected/) | Deliverability signals for outbound mail sent from the Agent Account. See [Agent Account webhook notifications](/docs/reference/notifications/agent-accounts/). |
| [`calendar.created`](/docs/reference/notifications/calendar/calendar-created/), [`calendar.updated`](/docs/reference/notifications/calendar/calendar-updated/), [`calendar.deleted`](/docs/reference/notifications/calendar/calendar-deleted/) | A calendar is created, updated, or deleted on the Agent Account. |
| [`event.created`](/docs/reference/notifications/events/event-created/), [`event.updated`](/docs/reference/notifications/events/event-updated/), [`event.deleted`](/docs/reference/notifications/events/event-deleted/) | Calendar events created, updated, or deleted on an Agent Account calendar. |
| [`contact.updated`](/docs/reference/notifications/contacts/contact-updated/), [`contact.deleted`](/docs/reference/notifications/contacts/contact-deleted/) | Contact records created, updated, or deleted. |
| [`grant.created`](/docs/reference/notifications/grants/grant-created/), [`grant.updated`](/docs/reference/notifications/grants/grant-updated/), [`grant.deleted`](/docs/reference/notifications/grants/grant-deleted/), [`grant.expired`](/docs/reference/notifications/grants/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

These resources are specific to Agent Accounts. Connected grants from other providers don't expose them.

| Resource | What it's for |
| --- | --- |
| [Policies](/docs/reference/api/policies/) | Bundle limits and spam detection. Attach one policy to a [workspace](/docs/reference/api/workspaces/) by setting its `policy_id`, and it governs every Agent Account in that workspace. |
| [Rules](/docs/reference/api/rules/) | Match inbound mail or outbound sends using `from.*`, `recipient.*`, and `outbound.type`, then apply actions (`block`, `mark_as_spam`, `assign_to_folder`, `mark_as_read`, `mark_as_starred`, `archive`, `trash`). |
| [Lists](/docs/reference/api/lists/) | Typed collections of domains, top-level domains (TLDs), or email addresses referenced by rules through the `in_list` operator. |
| [`GET /v3/grants/{grant_id}/rule-evaluations`](/docs/reference/api/rules/list-rule-evaluations/) | Audit which inbound or outbound rules ran most recently for the grant and what actions were applied. |
| [IMAP and SMTP submission](/docs/v3/agent-accounts/mail-clients/) | Connect standard mail clients to an Agent Account using an `app_password` on the grant. |

See [Policies, Rules, and Lists](/docs/v3/agent-accounts/policies-rules-lists/) for how these fit together, and [Mail client access](/docs/v3/agent-accounts/mail-clients/) for IMAP/SMTP setup.

## 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.
- **Templates and Workflows** (`/templates`, `/workflows`) — not implemented for Agent Account grants.
- **Scheduler** (`/v3/scheduling/*`): the Scheduler API and configurations aren't available for Agent Account grants yet.
- **Notetaker and conferencing**: the Notetaker API and conferencing integrations aren't supported for Agent Accounts yet.
- **Metadata**: tagging Agent Account resources with custom `metadata` and filtering by it isn't supported yet.
- **Contact groups** (`/contacts/groups`) — not implemented for Agent Accounts; contacts CRUD still works.
- **Full-text message search**: Agent Accounts run on Nylas-hosted infrastructure, so provider-specific search syntax (such as Gmail's `search_query_native`) doesn't apply, and full-text search isn't available yet. Filter messages with the standard query parameters (`from`, `to`, `subject`, `received_after`, and so on) in the meantime.

If you need one of these for an Agent Account today, let us know — these decisions will change as the product evolves.

## 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](/docs/v3/agent-accounts/mail-clients/), IMAP IDLE gives mail clients push-style updates without a webhook subscription.

## What's next

- [Agent Accounts quickstart](/docs/v3/getting-started/agent-accounts/) for an end-to-end flow that exercises the core endpoints
- [Provisioning Agent Accounts](/docs/v3/agent-accounts/provisioning/) to create Agent Accounts and attach policies
- [Policies, Rules, and Lists](/docs/v3/agent-accounts/policies-rules-lists/) for admin configuration and the rule-evaluations audit trail
- [Mail client access (IMAP & SMTP)](/docs/v3/agent-accounts/mail-clients/) to expose the mailbox to standard clients
- [Webhook notifications](/docs/v3/notifications/) for the complete payload schemas