# Nylas Agent Accounts

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

Nylas Agent Accounts are fully functional email and calendar identities that you create and control through the Nylas API. Each Agent Account is a real `name@company.com` mailbox — it sends and receives email, hosts and responds to calendar events, and is indistinguishable from a human-operated account to anyone interacting with it.

This is a different model from pointing an AI agent at a human's inbox. An Agent Account gives the agent a first-class identity — its own address, its own mailbox, its own calendar — that people and other agents communicate with directly. Think of it the way you'd think of any other user in your organization: reachable, persistent, and accountable for its own interactions.

Under the hood, an Agent Account is just another [grant](/docs/v3/auth/). It gets a `grant_id` that works with every existing Nylas endpoint — Messages, Drafts, Threads, Folders, Attachments, Calendars, Events, Webhooks — so anything you've built for connected accounts works for Agent Accounts with no new concepts.

> **Info:** 
> **New to Agent Accounts?** Start with the [Agent Accounts quickstart](/docs/v3/getting-started/agent-accounts/) to create your first account and send and receive a message in under 5 minutes.

## How teams use Agent Accounts

**Sales outreach agent.** A `sales-agent@yourcompany.com` mailbox runs cold outreach campaigns, threads replies through the Messages API, and classifies responses (interested / not now / unsubscribe) with an LLM. When a prospect says yes to a meeting, the same grant creates an event on the agent's own calendar and sends the invite.

**Customer support triage.** A `support@yourcompany.com` Agent Account receives every inbound support email. Rules block known spam domains at the SMTP stage, auto-route invoices to a finance folder, and mark VIP senders for immediate attention. An LLM drafts replies to common questions; humans approve the sensitive ones via a webhook flow.

**Scheduling bot with its own calendar.** A scheduling agent owns `scheduling@yourcompany.com`, parses meeting requests with an LLM, checks availability against its own calendar, proposes slots, and creates events that participants accept as normal invitations. See the [scheduling-agent tutorial](/docs/cookbook/use-cases/act/scheduling-agent-with-dedicated-identity/).

**Agent signup and testing.** A test agent provisions a fresh inbox per run, signs up for a third-party service, receives the verification email, extracts the link or OTP, and completes onboarding — no human in the loop. The inbox gets torn down when the test ends. See the [signup automation recipe](/docs/cookbook/agent-accounts/sign-up-for-a-service/).

**Voice-to-email follow-up.** A voice agent taking support calls sends documents, reset instructions, or meeting recaps from its own `voice-agent@yourcompany.com` address the moment the caller asks. The reply returns through the same Agent Account so the full conversation is one thread in the mailbox.

**Per-customer agent identities.** A multi-tenant app provisions one Agent Account per customer on each customer's own verified domain — `scheduling@customer-a.com`, `scheduling@customer-b.com` — each with its own policy, send quota, and sender reputation. All of them run in one Nylas application with the same code path.

## How Agent Accounts work

When you create an Agent Account, Nylas provisions a real mailbox on a domain you've registered (or on a Nylas-provided `*.nylas.email` trial domain). The account gets:

- An email address that can send outbound mail and receive inbound mail like any other mailbox.
- Six system folders provisioned automatically (`inbox`, `sent`, `drafts`, `trash`, `junk`, `archive`), plus any custom folders you create.
- A primary calendar that can host events and RSVP to invitations over standard iCalendar/ICS.
- A `grant_id` you use with the existing Nylas endpoints for messages, events, attachments, and webhooks.

You create Agent Accounts three ways: with the [Nylas CLI](/docs/v3/getting-started/cli/) (`nylas agent account create <email>`), from the Dashboard, or with [`POST /v3/connect/custom`](/docs/reference/api/manage-grants/byo_auth/) using `"provider": "nylas"` — the same Bring Your Own Authentication endpoint used for other providers. You can optionally attach a [policy](/docs/v3/agent-accounts/policies-rules-lists/) at creation to apply limits, spam detection, and inbound rules. Outbound rules are evaluated from enabled application rules during sends.

Inbound mail fires the standard [`message.created`](/docs/reference/notifications/messages/message-created/) webhook, identical in shape to `message.created` for any other grant.

## Why an Agent Account uses your own domain

Every Agent Account sends and receives on a domain you control, either a custom domain like `agents.yourcompany.com` or a Nylas-provided `*.nylas.email` trial domain. Using your own domain is what makes the agent a real, first-class sender instead of a shared address: people reply to it, calendars invite it, and its mail is authenticated as coming from you. It also means the account builds its own sender reputation, which a new domain establishes over about 4 weeks of gradual sending. Run one domain per customer or per use case to keep those reputations isolated, and see [Email deliverability for Agent Accounts](/docs/v3/agent-accounts/deliverability/) to protect and warm it.

## What you can do

| Capability | Description | Page |
| --- | --- | --- |
| **Set up a domain** | Register a custom domain and publish the DNS records Nylas needs to verify it. | [Setup domains](/docs/v3/agent-accounts/dns-provider-setup/) |
| **Provision accounts** | Create Agent Accounts on a verified domain — from the CLI (`nylas agent account create`), the Dashboard, or the API. | [Provisioning Agent Accounts](/docs/v3/agent-accounts/provisioning/) |
| **Send and receive email** | Use the same `/messages` and `/messages/send` endpoints you use for connected grants. Inbound attachment limits are set by your plan and the grant's policy; outbound messages are capped at 25 MB total. | [Messages API](/docs/v3/email/messages/) |
| **Host calendar events** | Create events, accept invitations, and RSVP on the primary calendar through the Events API. | [Events API](/docs/reference/api/events/) |
| **Manage contacts** | Read, create, update, and delete the account's own contacts through the Contacts API, and react to contact webhooks. | [Agent Account contacts](/docs/v3/agent-accounts/contacts/) |
| **Apply policies** | Bundle limits, spam detection, retention, and linked inbound rules; assign one policy to many accounts. | [Policies, Rules, and Lists](/docs/v3/agent-accounts/policies-rules-lists/) |
| **Filter inbound and outbound mail** | Match on sender fields for inbound rules, or sender, recipient, and `outbound.type` for outbound rules, then run actions like `block`, `mark_as_spam`, or `assign_to_folder`. | [Policies, Rules, and Lists](/docs/v3/agent-accounts/policies-rules-lists/) |
| **Maintain allow/block lists** | Typed collections of domains, TLDs, or addresses that rules reference through the `in_list` operator. | [Policies, Rules, and Lists](/docs/v3/agent-accounts/policies-rules-lists/) |
| **Receive webhooks** | Subscribe to `message.created` and the other grant-scoped triggers to be notified of inbound mail, state changes, and calendar activity. On top of those, Agent Accounts emit [deliverability webhooks](/docs/reference/notifications/agent-accounts/) like `message.delivered`, `message.bounced`, and `message.complaint` to track outbound mail. | [Webhooks](/docs/v3/notifications/) |
| **Expose IMAP and SMTP** | Give end users direct mail-client access to the Agent Account over standard IMAP and SMTP submission, alongside the API. | [Mail client access](/docs/v3/agent-accounts/mail-clients/) |

## Known limits

| Dimension | Default | Notes |
| --- | --- | --- |
| Send rate | 200 messages per account per day on the free plan | Paid plans have no daily cap by default. A stricter quota can be set through a [policy](/docs/v3/agent-accounts/policies-rules-lists/). |
| Storage | 3 GB per organization on the free plan | Higher storage available on paid plans. |
| Retention | 30 days inbox, 7 days spam on the free plan | Configurable through [policy retention limits](/docs/v3/agent-accounts/policies-rules-lists/). |
| Multi-domain | Unlimited | One Nylas application can manage Agent Accounts across any number of registered domains. |

## Before you begin

> **Info:** 
> **New to Nylas?** Start with the [Getting started guide](/docs/v3/getting-started/) to create your Nylas application and generate an API key.

To provision Agent Accounts, you also need a domain registered with Nylas — either a Nylas-provided `*.nylas.email` trial subdomain or your own custom domain with MX and TXT records configured. See [Setup domains](/docs/v3/agent-accounts/dns-provider-setup/).

## Related resources

- [Agent Accounts quickstart](/docs/v3/getting-started/agent-accounts/) for an end-to-end setup in under 5 minutes
- [Setup domains](/docs/v3/agent-accounts/dns-provider-setup/) to register a custom domain and publish its DNS records
- [Provisioning Agent Accounts](/docs/v3/agent-accounts/provisioning/) for account creation and multi-tenant patterns
- [Supported endpoints](/docs/v3/agent-accounts/supported-endpoints/) for the full reference of endpoints and webhooks that work with Agent Accounts
- [Email threading for agents](/docs/v3/agent-accounts/email-threading/) for how agents maintain conversation context across replies
- [Mail client access (IMAP & SMTP)](/docs/v3/agent-accounts/mail-clients/) to let end users connect Outlook, Apple Mail, and other clients
- [Policies, Rules, and Lists](/docs/v3/agent-accounts/policies-rules-lists/) for limit and spam configuration
- [Handle email replies](/docs/cookbook/agent-accounts/handle-replies/), [multi-turn conversations](/docs/cookbook/agent-accounts/multi-turn-conversations/), and [dedup patterns](/docs/cookbook/agent-accounts/prevent-duplicate-replies/) for building agent reply loops
- [Policies API reference](/docs/reference/api/policies/), [Rules API reference](/docs/reference/api/rules/), and [Lists API reference](/docs/reference/api/lists/)
- [BYO Auth reference](/docs/reference/api/manage-grants/byo_auth/) for the `nylas` provider variant
- [Managing domains](/docs/v3/email/domains/) for the Dashboard and API flow for registering and verifying domains