# Give your agent its own email

Source: https://developer.nylas.com/docs/v3/getting-started/agent-own-email/

Give your AI agent a real, independent `agent@yourdomain.com` mailbox it fully owns — not a borrowed seat in a human's inbox. Messages the agent sends come from the agent's own address, replies land in a dedicated inbox, and every interaction is isolated from any human account. This is what a [Nylas Agent Account](/docs/v3/agent-accounts/) is for: a Nylas-hosted mailbox you create and control entirely through the API.

Use this pattern when you want:

- An agent identity that sends from `sales-agent@yourcompany.com`, `support-agent@yourcompany.com`, or any other address you control.
- Replies that stay in the agent's inbox instead of clogging a human's.
- Persistent threaded conversations the agent owns — CRM outreach, support triage, scheduling negotiation, automated follow-ups.
- Multi-agent deployments where each agent has its own mailbox, domain, and sender reputation.

If you'd rather have the agent act on your personal inbox, see [Share your email with your agent](/docs/v3/getting-started/agent-email/) instead.

## Prerequisites

- A Nylas API key. If you don't have one yet, follow the [Getting started with the CLI](/docs/v3/getting-started/cli/) or [Dashboard](/docs/v3/getting-started/dashboard/) guide.
- A domain registered with Nylas — either a Nylas-provided `*.nylas.email` trial subdomain for prototyping, or your own domain with MX + TXT records in place. See [Setup domains](/docs/v3/agent-accounts/dns-provider-setup/).

## Create the Agent Account

The fastest path is the [Nylas CLI](/docs/v3/getting-started/cli/):

```bash
nylas agent account create sales-agent@agents.yourcompany.com
```

The CLI prints the new grant ID — save it, because the agent uses it on every subsequent call. `nylas agent account list` shows every Agent Account on the application, and `nylas auth list` includes them alongside connected grants.

Prefer the API? Use [`POST /v3/connect/custom`](/docs/reference/api/manage-grants/byo_auth/) with `"provider": "nylas"`. You only need the email address — there's no OAuth refresh token to manage.

```bash
curl --request POST \
  --url "https://api.us.nylas.com/v3/connect/custom" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "provider": "nylas",
    "settings": {
      "email": "sales-agent@agents.yourcompany.com"
    }
  }'
```

The response contains a `grant_id`. Save it — from this point on, the agent can drive the account with any Nylas grant-scoped endpoint, exactly like a connected grant.

## Send email as the agent

Your agent sends outbound with [`POST /v3/grants/{grant_id}/messages/send`](/docs/reference/api/messages/send-message/). Recipients see a normal message from the agent's address — no relay footer, no "sent via" branding.

```bash
curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages/send" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "subject": "Following up on our demo",
    "body": "Hi Alice — great talking with you yesterday. A few next steps...",
    "to": [{ "email": "alice@example.com", "name": "Alice" }]
  }'
```

## Receive replies the agent can act on

Register a `message.created` webhook and your agent gets notified as soon as a reply arrives. The payload shape is identical to `message.created` for any other grant.

From the [Nylas CLI](/docs/v3/getting-started/cli/):

```bash
nylas webhook create \
  --url https://youragent.example.com/webhooks/nylas \
  --triggers "message.created,message.updated"
```

Or through the API:

```bash
curl --request POST \
  --url "https://api.us.nylas.com/v3/webhooks" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "trigger_types": ["message.created", "message.updated"],
    "callback_url": "https://youragent.example.com/webhooks/nylas"
  }'
```

If your agent polls instead of listening, list the mailbox on a cadence:

```bash
curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages?unread=true&limit=20" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"
```

## Apply limits and filtering

Every endpoint for connected grants works against an Agent Account. On top of that, three admin APIs let you configure how each mailbox behaves:

- [Policies](/docs/v3/agent-accounts/policies-rules-lists/) bundle send quotas, attachment limits, retention, and spam settings you can reuse across agents.
- [Rules](/docs/v3/agent-accounts/policies-rules-lists/) block, mark as spam, or auto-route inbound messages based on `from.address`, `from.domain`, or `from.tld`.
- [Lists](/docs/v3/agent-accounts/policies-rules-lists/) hold typed collections of domains or addresses that rules match against with `in_list`.

Policies and rules attach to [workspaces](/docs/v3/agent-accounts/policies-rules-lists/), not individual grants: set `policy_id` and `rule_ids` on a workspace and every Agent Account in it inherits them. Accounts you don't assign land in your application's default workspace.

## Multi-agent patterns

One Nylas application can run any number of Agent Accounts across any number of registered domains. Common setups:

- **Per-customer identity** — each customer gets `agent@<their-domain>.com`, provisioned programmatically.
- **Per-workflow identity** — `sales-agent@...`, `support-agent@...`, `scheduling-agent@...` on the same domain, each with its own policy.
- **Reputation isolation** — high-volume outbound split across `a.yourdomain.com`, `b.yourdomain.com` so issues on one don't contaminate the others.

## Handle replies and threading

The agent's mailbox is bidirectional -- it sends email and receives replies on the same address, in the same thread. When someone replies to a message the agent sent, Nylas groups it into the same thread automatically using `In-Reply-To` and `References` headers. The `message.created` webhook includes a `thread_id` you can use to match the reply to the original conversation without parsing headers yourself.

For the full pattern -- detecting replies, restoring conversation context, replying in-thread, and managing multi-turn state -- see these guides:

- [Email threading for agents](/docs/v3/agent-accounts/email-threading/) -- how threading works at the protocol level and how to map threads to agent state
- [Handle email replies in an agent loop](/docs/cookbook/agent-accounts/handle-replies/) -- webhook-driven recipe for detecting and routing replies
- [Build a multi-turn email conversation](/docs/cookbook/agent-accounts/multi-turn-conversations/) -- the full send-receive-respond loop with persistent state

## Let humans connect to the mailbox too

If you want humans — the agent's human collaborator, an ops team, a customer — to access the agent's mailbox from Outlook, Apple Mail, or another standard client, set an `app_password` on the grant. IMAP + SMTP submission stream the same mailbox the API reads and writes. See [Mail client access (IMAP & SMTP)](/docs/v3/agent-accounts/mail-clients/) for the full setup.

## What's next

- **[Agent Accounts overview](/docs/v3/agent-accounts/)** -- the full product doc, including capabilities, limits, and architecture
- **[Agent Accounts quickstart](/docs/v3/getting-started/agent-accounts/)** -- step-by-step setup with webhooks and a first end-to-end send/receive
- **[Give your agent its own calendar](/docs/v3/getting-started/agent-own-calendar/)** -- use the same Agent Account grant for scheduling
- **[Supported endpoints for Agent Accounts](/docs/v3/agent-accounts/supported-endpoints/)** -- reference of every grant-scoped endpoint and webhook
- **[Policies, Rules, and Lists](/docs/v3/agent-accounts/policies-rules-lists/)** -- configure limits, spam detection, and inbound filtering