Give your AI agent a real email address on your own domain

Most "AI agent that emails for you" demos point a language model at a human's Gmail inbox over OAuth. That works until the agent needs its own identity: an address people reply to, a calendar that accepts invites, a mailbox your application owns end to end. Borrowing a human's inbox means inheriting their OAuth scopes, their rate limits, and the awkwardness of an agent sending mail as a person who didn't write it.

A Nylas Agent Account flips that around. It's a real [e-mail] mailbox that you create and control entirely through the API — it sends, receives, hosts calendar events, and RSVPs, and it's indistinguishable from a human-operated account to anyone on the other end. Under the hood it's just a grant, so the grant_id you get back works with the same grant-scoped endpoints — Messages, Threads, Folders, Drafts, Attachments, Contacts, Calendars, and Events — you've already used for connected accounts, plus the standard webhook triggers.

This post is a working tour of provisioning one, from two angles: the HTTP API for your backend, and the Nylas CLI for the terminal and quick experiments. I work on the CLI, so the terminal commands below are the exact ones I reach for.

Why an Agent Account beats borrowing a human inbox

An Agent Account is a first-class sender, not a delegated one. When the agent owns [e-mail], people reply to it directly, calendars invite it as a normal participant, and its mail authenticates as coming from you. A few concrete differences from pointing an agent at someone's existing mailbox:

• No OAuth flow to babysit. Creation needs only an email address on a domain you've registered — there's no refresh token to store or rotate, and the grant rarely expires because there's no OAuth token to refresh.
• Its own reputation. The account sends on your domain, and a new domain establishes its sender reputation over roughly four weeks of gradual sending. That reputation is yours to protect, not a shared corporate inbox's.
• Per-tenant isolation. You can run one account per customer on each customer's own verified domain, each with its own send quota and reputation, all from one Nylas application and the same code path.

The mental model is simple: treat the agent like any other user in your org. Reachable, persistent, accountable for its own mail.

What you get when you provision one

Provisioning an Agent Account creates a hosted mailbox on a domain you've registered and returns a grant_id. That single ID is everything you need — the existing Messages, Threads, Folders, Drafts, Attachments, Contacts, Calendars, and Events endpoints all work against /v3/grants/{grant_id}/... exactly as they do for any other grant. Each new account comes with:

• A primary email address that sends and receives like any mailbox.
• Six system folders provisioned automatically: inbox, sent, drafts, trash, junk, and archive. System folder names are reserved; you can add custom folders alongside them.
• A primary calendar that hosts events and RSVPs to invitations over standard iCalendar.
• An optional app password for IMAP and SMTP access, so a human can connect Outlook or Apple Mail to the same mailbox.

There's no separate SDK, URL prefix, or auth scheme. If you've built against a connected Gmail or Microsoft grant before, the message and calendar surface is unchanged — provisioning, the domain, and the optional workspace and app-password settings are the new pieces.

Register a domain first

Every Agent Account lives on a domain, and you pick one of two strategies before creating any accounts. The fastest is a Nylas trial domain; the production path is your own domain with DNS records you publish once.

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

A trial domain needs no DNS work, so you can create test@<your-app>.nylas.email and start sending in minutes. A custom domain uses up to five records: a TXT for ownership, a TXT for DKIM, a TXT for SPF, and two MX records (one for inbound delivery, one for the feedback loop). Nylas verifies them automatically once they propagate, and DNS can take up to 24 hours depending on the record's TTL. DMARC isn't one of the records Nylas verifies, but add it for production to protect the domain against spoofing. The full provider-by-provider walkthrough lives in Set up domains. I'd recommend a dedicated subdomain like agents.yourcompany.com for production so the agent's sender reputation stays isolated from your marketing mail.

Create an Agent Account from the CLI

Once a domain is verified, the Nylas CLI exposes the whole workflow. After nylas init creates an account and API key, nylas agent account create provisions the grant and prints its id, status, and connector details. It's the path I use when I want a mailbox in one line to test against.

# Create the Agent Account
nylas agent account create [e-mail]

# Create with IMAP/SMTP access enabled from the start
nylas agent account create [e-mail] \
  --app-password "MySecureP4ssword!2024"

# List, fetch, and check connector readiness
nylas agent account list
nylas agent account get [e-mail]
nylas agent status

Agent Accounts also show up in nylas auth list next to your connected grants, so the agent's mailbox sits alongside everything else you've authenticated. To see what's configured, nylas agent policy list and nylas agent rule list show the policies and rules defined on your application. When you're done with a throwaway account, nylas agent account delete [e-mail] --yes tears it down without the confirmation prompt.

Create an Agent Account programmatically

For your backend, provisioning is one request to POST /v3/connect/custom with "provider": "nylas" — the same Bring Your Own Authentication endpoint other providers use. Unlike OAuth providers, this flow needs no refresh token, only an email address on a registered domain. The response hands back the grant_id you'll use on every later call.

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": "[e-mail]"
    }
  }'

The response contains data.id — save it, because that's the grant_id for the mailbox. The top-level name field sets the account's display name, which Nylas uses as the default From name on outbound mail, so recipients see Sales Agent <[e-mail]> instead of a bare address. Omit name and the account sends with no display name. Note that name sits alongside provider and settings in the body, not inside settings — that placement trips people up.

To use a different sender 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/<GRANT_ID>/messages/send" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "from": [{ "name": "Acme Billing", "email": "[e-mail]" }],
    "to": [{ "email": "[e-mail]" }],
    "subject": "Your invoice",
    "body": "Thanks for your business."
  }'

Enable IMAP and SMTP access with an app password

Sometimes you want a human in the loop — an agent handles routine mail via the API while a person reviews the tricky messages from Outlook or Apple Mail. Setting an app_password on the grant turns on IMAP and SMTP submission so standard clients can sign in. Without one, protocol access stays disabled and every client login is rejected.

The password must be 18 to 40 printable ASCII characters with at least one uppercase letter, one lowercase letter, and one digit. Nylas validates it on write and stores it as a bcrypt hash, so you can't read it back later — only reset it. Pass it in settings at creation:

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": "[e-mail]",
      "app_password": "MySecureP4ssword!2024"
    }
  }'

IMAP and the API read and write the same mailbox: a flag change, folder move, or send through either surface shows up in the other within seconds. New inbound mail and sent messages fire message.created, while flag, folder, and delete changes fire message.updated. Clients connect to mail.us.nylas.email (or mail.eu.nylas.email in the EU) on port 993 for IMAP and 465 or 587 for SMTP. The mail client guide has the full settings table.

Group accounts with workspaces

Policies and rules — send quotas, spam settings, mail filters — apply through workspaces, not individual grants. Pass a top-level workspace_id at creation to drop the new account into a specific workspace, and it inherits that workspace's limits and rules. This is how you give a whole class of agents the same configuration in one place.

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": "[e-mail]"
    }
  }'

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

Verify the account works

After you have a grant_id, the fastest sanity check is to send a test email to the new address from any external client, then list the mailbox. The same GET /messages you'd use on a Gmail grant works here unchanged — that's the whole point of the shared surface.

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

If you've registered a message.created webhook, you'll also get a notification as soon as mail lands, with the same payload shape as message.created for any other grant. From the CLI, the standard nylas email commands run against the agent grant, so nylas email list checks the mailbox in one line.

Multi-domain and multi-tenant patterns

A single Nylas application can manage Agent Accounts across any number of registered domains, which is what makes the per-customer model practical. Three patterns come up most often:

• Per-customer domains. Your customers bring their own domains; you register each one and provision agents on their behalf, so [e-mail] and [e-mail] each carry their own reputation.
• Sender-reputation isolation. Split high-volume outbound across sales-a.yourcompany.com, sales-b.yourcompany.com, and so on, so a deliverability problem on one domain doesn't contaminate the others.
• Environment separation. Run agents.staging.yourcompany.com and agents.yourcompany.com on the same application to keep staging traffic off the production domain.

On the free plan, each account sends up to 200 messages per day and the organization gets 3 GB of storage, with 30-day inbox retention; paid plans lift the daily send cap and raise storage. Those defaults are usually fine to start, and you can tighten them with a workspace policy when you need to.

Wrapping up

Provisioning an Agent Account is one CLI command or one API call, and from the grant_id forward it's the same Email and Calendar surface you already know. The pieces worth getting right up front are the domain (trial for speed, custom subdomain for production), the display name, and the workspace the account belongs to — everything else is the standard grant API.

Where to go next:

• Agent Accounts overview — the full concept guide and capabilities
• Agent Accounts quickstart — send and receive your first message in under 5 minutes
• Set up domains — register a custom domain and publish its DNS records
• Supported endpoints — every endpoint and webhook that works with Agent Account grants
• Nylas CLI agent commands — the full nylas agent reference