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 [email protected] 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 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 [email protected], 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, andarchive. 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 | [email protected] | 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 exposes the whole workflow. After 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 [email protected]
# Create with IMAP/SMTP access enabled from the start
nylas agent account create [email protected] \
--app-password "MySecureP4ssword!2024"
# List, fetch, and check connector readiness
nylas agent account list
nylas agent account get [email protected]
nylas agent status
Agent Accounts also show up in 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": "[email protected]"
}
}'
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 <[email protected]> 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": "[email protected]" }],
"to": [{ "email": "[email protected]" }],
"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": "[email protected]",
"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 , 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": "[email protected]"
}
}'
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 — the full concept guide and capabilities
— register a custom domain and publish its DNS records
— the full
nylas agent reference
SOCIAL SHARE CARD GENERATOR