Provisioning Agent Accounts

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.

Set up a domain first. See Setup domains 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, the Nylas CLI exposes the full Agent Accounts workflow:

# Create the Agent Account
nylas agent account create [email protected]

# Create with IMAP/SMTP access enabled from the start
nylas agent account create [email protected] --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 [email protected]

# 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 [email protected] --yes

nylas agent account create provisions the grant and prints the id, status, and connector details. Agent Accounts also show up in nylas auth list alongside connected grants. See the agent command reference for the full set of subcommands — agent account list, agent account get, agent account delete, agent status, agent policy list, and 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 with "provider": "nylas". Unlike OAuth providers, this flow doesn’t need a refresh token — only the email address on a registered domain.

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": "[email protected]"
    }
  }'

{
  "request_id": "5967ca40-a2d8-4ee0-a0e0-6f18ace39a90",
  "data": {
    "id": "b1c2d3e4-5678-4abc-9def-0123456789ab",
    "provider": "nylas",
    "grant_status": "valid",
    "email": "[email protected]",
    "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 <[email protected]> instead of the bare address. The name sits alongside provider and settings in the request body, not inside settings.

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": "[email protected]"
    }
  }'

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:

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": "[email protected]" }],
    "to": [{ "email": "[email protected]" }],
    "subject": "Your invoice",
    "body": "Thanks for your business."
  }'

Assign a workspace at creation

Policies and rules apply through workspaces, 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.

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": "[email protected]"
    }
  }'

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:

nylas agent account create [email protected] --app-password "MySecureP4ssword!2024"

Or through the API, pass app_password in settings:

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": "[email protected]",
      "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 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.
`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. 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:

If you’ve registered a 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 to register a custom domain and publish its DNS records
Policies, Rules, and Lists for limit, spam, and inbound-filter configuration
Managing domains for the full DNS setup and verification flow
Agent Accounts quickstart for an end-to-end setup with webhooks
BYO Auth reference for the full nylas provider schema
Webhooks to configure message.created notifications for Agent Accounts