# Provisioning Agent Accounts

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

Every Agent Account lives on a domain. Once you've set up a domain to host on, you can create accounts at any address under it from the CLI, the Dashboard, or the API. This page covers creating and managing those accounts.

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

Set up a domain first. See [Setup domains](/docs/v3/agent-accounts/dns-provider-setup/) to choose a Nylas trial domain or register a custom domain and publish its DNS records. Once your domain is verified, come back here to create accounts on it.

## Create an Agent Account

Once your domain is verified, you can create Agent Accounts at any address under it. Three paths — in rough order of setup effort.

### From the CLI

After [`nylas init`](https://cli.nylas.com/docs/commands/init), the [Nylas CLI](https://cli.nylas.com/) exposes the full Agent Accounts workflow:

```bash
# Create the Agent Account
nylas agent account create agent@agents.yourcompany.com

# Create with IMAP/SMTP access enabled from the start
nylas agent account create agent@agents.yourcompany.com --app-password "MySecureP4ssword!2024"

# List all Agent Accounts on the application
nylas agent account list
nylas agent account list --json

# Get a single Agent Account by ID or email
nylas agent account get agent@agents.yourcompany.com

# Check connector readiness
nylas agent status

# List policies and rules attached to accounts
nylas agent policy list
nylas agent rule list

# Delete by grant ID or email (--yes skips the confirmation prompt)
nylas agent account delete agent@agents.yourcompany.com --yes
```

[`nylas agent account create`](https://cli.nylas.com/docs/commands/agent-account-create) provisions the grant and prints the `id`, status, and connector details. Agent Accounts also show up in [`nylas auth list`](https://cli.nylas.com/docs/commands/auth-list) alongside connected grants. See the [agent command reference](https://cli.nylas.com/docs/commands/agent-account-list) for the full set of subcommands — [`agent account list`](https://cli.nylas.com/docs/commands/agent-account-list), [`agent account get`](https://cli.nylas.com/docs/commands/agent-account-get), [`agent account delete`](https://cli.nylas.com/docs/commands/agent-account-delete), [`agent status`](https://cli.nylas.com/docs/commands/agent-status), [`agent policy list`](https://cli.nylas.com/docs/commands/agent-policy-list), and [`agent rule list`](https://cli.nylas.com/docs/commands/agent-rule-list).

### From the Dashboard

In the left navigation, open **Agent Accounts → Accounts** and click **Create account**. Pick a registered domain and an alias. The account is live immediately and you can view its inbox from the Dashboard.

### Programmatically

Use [`POST /v3/connect/custom`](/docs/reference/api/manage-grants/byo_auth/) with `"provider": "nylas"`. Unlike OAuth providers, this flow doesn't need a refresh token — only the email address on a registered domain.

```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",
    "name": "Sales Agent",
    "settings": {
      "email": "sales-agent@agents.yourcompany.com"
    }
  }'
```

```json [createAgentAccount-Response (JSON)]
{
  "request_id": "5967ca40-a2d8-4ee0-a0e0-6f18ace39a90",
  "data": {
    "id": "b1c2d3e4-5678-4abc-9def-0123456789ab",
    "provider": "nylas",
    "grant_status": "valid",
    "email": "sales-agent@agents.yourcompany.com",
    "name": "Sales Agent",
    "scope": [],
    "created_at": 1742932766
  }
}
```

Save the `data.id` — that's the `grant_id` you'll use on every subsequent call.

### Set a display name

Pass a top-level `name` to give the account a display name. Nylas stores it on the grant and uses it as the default `From` name on every message the account sends, so recipients see `Sales Agent <sales-agent@agents.yourcompany.com>` instead of the bare address. The `name` sits alongside `provider` and `settings` in the request body, not inside `settings`.

```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",
    "name": "Sales Agent",
    "settings": {
      "email": "sales-agent@agents.yourcompany.com"
    }
  }'
```

If you omit `name`, the account sends with no display name. To use a different name on a single message without changing the account's stored name, set the `from` field when you [send](/docs/reference/api/messages/send-message/):

```bash
curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/send" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "from": [{ "name": "Acme Billing", "email": "sales-agent@agents.yourcompany.com" }],
    "to": [{ "email": "customer@example.com" }],
    "subject": "Your invoice",
    "body": "Thanks for your business."
  }'
```

### Assign a workspace at creation

Policies and rules apply through [workspaces](/docs/v3/agent-accounts/policies-rules-lists/), not individual grants. Pass a top-level `workspace_id` to place the new Agent Account in a specific workspace; the account picks up that workspace's policy limits, spam settings, and rules.

```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",
    "workspace_id": "<WORKSPACE_ID>",
    "settings": {
      "email": "sales-agent@agents.yourcompany.com"
    }
  }'
```

If you omit `workspace_id`, the account is auto-grouped into a workspace whose `domain` matches the email address (when `auto_group` is enabled), or placed in your application's default workspace. You can move an existing account later with `PATCH /v3/grants/{grant_id}` and a new `workspace_id`.

### Enable IMAP and SMTP access

Set `app_password` if you want end users to connect mail clients (Outlook, Apple Mail, Thunderbird, and so on) to the Agent Account over IMAP and SMTP submission in addition to using the API. The password is stored as a bcrypt hash — Nylas validates it on write and you can't retrieve it later, only reset it.

From the CLI, pass it at creation time:

```bash
nylas agent account create agent@yourdomain.com --app-password "MySecureP4ssword!2024"
```

Or through the API, pass `app_password` in `settings`:

```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": "agent@yourdomain.com",
      "app_password": "MySecureP4ssword!2024"
    }
  }'
```

The password must be 18–40 printable ASCII characters with at least one uppercase letter, one lowercase letter, and one digit. If you omit `app_password`, protocol-level access stays disabled and IMAP/SMTP clients reject authentication. See [Connect mail clients to an Agent Account](/docs/v3/agent-accounts/mail-clients/) for the full setup.

### Settings reference

| Setting | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | Yes | The Agent Account email address. The domain must match a [registered domain](/docs/v3/email/domains/). |
| `app_password` | string | No | Password for IMAP and SMTP-submission access. 18–40 printable ASCII characters with at least one uppercase letter, one lowercase letter, and one digit. Bcrypt-hashed on write. Without this, protocol access stays disabled. |

To apply limits, spam detection, or mail rules, attach a [policy to the account's workspace](/docs/v3/agent-accounts/policies-rules-lists/). Both `name` and `workspace_id` are top-level fields on the request, not `settings` entries.

## Verify the account works

After you have a `grant_id`, send a test email to the new address from any external client. Then list the mailbox:

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

If you've registered a [`message.created`](/docs/reference/notifications/messages/message-created/) webhook, you should also receive a notification as soon as mail lands. The payload has the same shape as `message.created` for any other grant.

## Multi-domain and multi-tenant patterns

A single Nylas application can manage Agent Accounts across any number of registered domains. Common patterns:

- **Per-customer domains.** Your customers bring their own domains. You register each one and provision Agent Accounts on their behalf.
- **Sender-reputation isolation.** High-volume outbound split across `sales-a.yourcompany.com`, `sales-b.yourcompany.com`, and so on, so that issues on one domain don't contaminate the others.
- **Environment separation.** `agents.staging.yourcompany.com` and `agents.yourcompany.com` on the same application, so that staging traffic stays off the production domain.

## What's next

- [Setup domains](/docs/v3/agent-accounts/dns-provider-setup/) to register a custom domain and publish its DNS records
- [Policies, Rules, and Lists](/docs/v3/agent-accounts/policies-rules-lists/) for limit, spam, and inbound-filter configuration
- [Managing domains](/docs/v3/email/domains/) for the full DNS setup and verification flow
- [Agent Accounts quickstart](/docs/v3/getting-started/agent-accounts/) for an end-to-end setup with webhooks
- [BYO Auth reference](/docs/reference/api/manage-grants/byo_auth/) for the full `nylas` provider schema
- [Webhooks](/docs/v3/notifications/) to configure `message.created` notifications for Agent Accounts