Provisioning Agent Accounts

Every Agent Account lives on a domain. Before you can create one, pick a domain to host on — either a shared Nylas trial domain (instant, no DNS setup) or a domain you own (MX and TXT records at your DNS provider). This page walks through both paths and shows how to create accounts once a domain is ready.

Choose a domain strategy

Strategy	Address format	Setup	When to use
Nylas trial domain	`alias@<your-application>.nylas.email`	None — register from the Dashboard	Prototyping, local testing, demos
Your own domain	`[email protected]`	MX and TXT records at your DNS provider	Production, customer-facing agents, branded mail

You can mix both strategies in one Nylas application. Many customers prototype on *.nylas.email and move to a custom domain before launch.

Register a custom domain

You register a domain once per Nylas organization, then create as many Agent Accounts under it as your plan allows.

Register the domain with Nylas. From the Dashboard, add the domain and pick the data center region (US or EU) where your application lives. You can also register through the API — see Managing domains.
Publish DNS records at your DNS provider. Nylas generates the MX record (routes inbound mail to Nylas) and TXT records (prove ownership and configure SPF/DKIM for outbound) you need to publish. Add them at your DNS provider.
Wait for verification. Once the records propagate, Nylas verifies them automatically. The domain status moves to verified and is ready to host Agent Accounts.

We recommend a dedicated subdomain for production use — for example, agents.yourcompany.com — so that sender reputation on Agent Accounts is isolated from your primary marketing domain.

For the step-by-step DNS record flow and the verification API, see Managing domains.

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 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.

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",
    "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]",
    "scope": [],
    "created_at": 1742932766
  }
}

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

Apply a policy at creation

If you’ve created a policy, pass policy_id in settings to apply it to the new grant.

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]",
      "policy_id": "<POLICY_ID>"
    }
  }'

If you omit policy_id, the grant inherits whatever policy_id is configured on the application’s nylas connector, if any. You can change the policy on an existing grant by updating its settings.

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.
`policy_id`	string (UUID)	No	A policy to apply to this grant. Inherited from the `nylas` connector when omitted.
`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.

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 — branch on the grant’s provider ("nylas") if you need to distinguish Agent Account deliveries from connected-grant deliveries.

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

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