Most "AI email" demos point a model at a human's inbox over OAuth. That's fine until you want the agent to be a participant — to have its own address that people reply to, that calendars invite, and that builds its own sender reputation. Pointing at someone's personal inbox doesn't give you that.
Nylas Agent Accounts take the other approach: a real name@yourdomain.com
mailbox and calendar that the agent owns end to end. It sends, receives, hosts events, and RSVPs — and to anyone on the other side it's indistinguishable from a human-operated account. It went GA in June 2026.
The part I like as an SRE: it's not a new API surface. An Agent Account is just another Nylas grant. It gets a grant_id
that works with every endpoint you already use — Messages, Drafts, Threads, Folders, Attachments, Calendars, Events, Webhooks. Nothing new to learn on the data plane.
This walkthrough provisions one two ways (CLI and raw API), then sends, receives, RSVPs, and adds guardrails.
When you create an Agent Account, Nylas provisions a real mailbox on a domain you've registered (or a Nylas *.nylas.email
trial domain). Each account comes with:
inbox
, sent
, drafts
, trash
, junk
, archive
), plus any custom ones you creategrant_id
for all the existing Nylas endpointsYou need two things:
nylas init
creates an account and generates a key in one command.*.nylas.email
trial subdomain (good for testing in minutes) or your own custom domain with MX + TXT records. Register it under Organization Settings → Domains.Why your own domain? It's what makes the agent a real first-class sender instead of a shared relay address — people reply to it, calendars invite it, and its mail authenticates as coming from you. A new domain builds sender reputation over roughly four weeks of gradual sending, so run one domain per customer or use case to keep reputations isolated.
After nylas init
, provisioning is one command:
nylas agent account create test@your-application.nylas.email
The CLI prints the new grant ID alongside connector and status details. A few companion commands:
nylas agent account list
nylas agent status
nylas agent account get test@your-application.nylas.email
nylas agent overview
That last one — nylas agent overview
— renders a tree per account and flags dangling references to deleted policies/rules. It's the command I'd reach for first when something looks misconfigured.
Under the hood the CLI calls POST /v3/connect/custom with
"provider": "nylas"
— the same Bring Your Own Auth endpoint used for other providers, minus the refresh token. Just the email 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": "Test Agent",
"settings": {
"email": "test@your-application.nylas.email"
}
}'
The response contains a grant_id
— save it, you'll use it everywhere. The top-level name
sets the display name recipients see on outbound mail (Test Agent <test@your-application.nylas.email>
). Omit it and the account sends with no display name.
Two ways, same as any grant.
Poll the messages endpoint:
curl --request GET \
--url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages?limit=5" \
--header "Authorization: Bearer <NYLAS_API_KEY>"
Or subscribe to a webhook so Nylas calls you the moment mail arrives. From the CLI:
nylas webhook create \
--url https://yourapp.example.com/webhooks/nylas \
--triggers message.created
Inbound mail fires the standard message.created
webhook — identical in shape to message.created
for any other grant, so a handler you already have just works. On top of that, Agent Accounts emit deliverability webhooks like message.delivered
, message.bounced
, and message.complaint
for tracking outbound mail.
Same /messages/send
endpoint you'd use for a connected grant:
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 '{
"subject": "Hello from my Agent Account",
"body": "This message was sent by a Nylas Agent Account.",
"to": [{ "email": "you@yourdomain.com", "name": "You" }]
}'
The recipient sees a normal message from the agent's address — no "sent via" branding, no relay footer.
Every Agent Account ships with a primary calendar, reachable through the same Events endpoints:
GET /v3/grants/{grant_id}/events
— list eventsPOST /v3/grants/{grant_id}/events
— create an event and invite othersPOST /v3/grants/{grant_id}/events/{id}/send-rsvp
— accept or decline an invitationInvitations travel over standard iCalendar/ICS, so Google Calendar, Microsoft 365, and Apple Calendar all treat the agent as a normal participant. This is what lets a scheduling agent propose slots and have participants accept them as ordinary invites.
Provisioning gives you a working mailbox. The interesting operational part is constraining what it can do. Three application-scoped resources handle that:
block
, mark_as_spam
, assign_to_folder
, archive
, or trash
.in_list
operator.They attach through workspaces, not individual grants: a workspace carries one policy_id
and an array of rule_ids
, and every account in it inherits both. Each application has a default workspace, so configuring it governs all your unassigned accounts at once.
Inspect them from the CLI:
nylas agent policy list
nylas agent rule list
nylas agent list list
And create each piece from the CLI:
nylas agent list create --name "Blocked domains" --type domain --item spam.com
nylas agent rule create \
--name "Archive outbound mail" \
--trigger outbound \
--condition recipient.domain,is,example.com \
--action archive
nylas agent policy create --name "Strict Policy"
Swap --action archive
for --action block
and the rule rejects the message instead — before it ever reaches the mailbox (inbound) or the provider (outbound). That's handy for data-loss prevention, keeping test domains out of production, or stopping an agent from emailing the wrong people. Inbound and outbound rules are isolated: inbound rules never run on sends, and outbound rules never re-evaluate the stored sent copy.
Policies are optional. Skip them and the account runs at your billing plan's maximum limits and delivers every inbound message to the inbox.
| Dimension | Default | Notes |
|---|---|---|
| Send rate | 200 messages/account/day | Paid plans have no daily cap by default |
| Storage | 3 GB/org | Higher on paid plans |
| Retention | 30 days inbox, 7 days spam | Configurable via policy |
| Domains | Unlimited | One application can manage accounts across any number of domains |
The thing that makes Agent Accounts click is that there's no second system. You provision an identity with one CLI command or one API call, and from that point it's the same Messages, Events, and Webhooks surface you'd use for a connected Gmail or Microsoft grant — now owned by your agent instead of borrowed from a user.
If you want to go deeper:
Written by Qasim Muhammad and Pouya Sanooei.