DEV Community

Qasim
Qasim

Posted on

Give your AI agent its own inbox: Nylas Agent Accounts via API and CLI

#ai #email #api #devtools

Nylas Agent Accounts via API and CLI

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.

What you get

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:

  • An email address that sends and receives like any other mailbox
  • Six system folders (inbox, sent, drafts, trash, junk, archive), plus any custom ones you create
  • A primary calendar that hosts events and RSVPs over standard iCalendar/ICS
  • A grant_id for all the existing Nylas endpoints

Before you begin

You need two things:

  1. A Nylas API key. The fastest path is the CLI — nylas init creates an account and generates a key in one command.
  2. A domain. Either a Nylas-provided *.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.

Create an Agent Account

Option A — the CLI (fastest)

After nylas init, provisioning is one command:

nylas agent account create test@your-application.nylas.email
Enter fullscreen mode Exit fullscreen mode

The CLI prints the new grant ID alongside connector and status details. A few companion commands:

# List every agent account
nylas agent account list

# Confirm the connector is ready
nylas agent status

# Show one account
nylas agent account get test@your-application.nylas.email

# See how accounts, workspaces, policies, rules, and lists fit together
nylas agent overview
Enter fullscreen mode Exit fullscreen mode

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.

Option B — the API

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"
    }
  }'
Enter fullscreen mode Exit fullscreen mode

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.

Receive mail

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>"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

Send 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" }]
  }'
Enter fullscreen mode Exit fullscreen mode

The recipient sees a normal message from the agent's address — no "sent via" branding, no relay footer.

Use the calendar

Every Agent Account ships with a primary calendar, reachable through the same Events endpoints:

  • GET /v3/grants/{grant_id}/events — list events
  • POST /v3/grants/{grant_id}/events — create an event and invite others
  • POST /v3/grants/{grant_id}/events/{id}/send-rsvp — accept or decline an invitation

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

Guardrail it: policies, rules, and lists

Provisioning gives you a working mailbox. The interesting operational part is constraining what it can do. Three application-scoped resources handle that:

  • Policies bundle limits (send quota, storage, retention, attachment caps) and spam settings. One policy governs many accounts.
  • Rules match inbound or outbound mail on sender/recipient fields and run actions like block, mark_as_spam, assign_to_folder, archive, or trash.
  • Lists are typed collections of domains, TLDs, or addresses that rules reference via the 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
Enter fullscreen mode Exit fullscreen mode

And create each piece from the CLI:

# A typed list of domains you can reference from a rule's in_list condition
nylas agent list create --name "Blocked domains" --type domain --item spam.com

# An outbound rule that archives the sent copy of mail to a recipient domain
nylas agent rule create \
  --name "Archive outbound mail" \
  --trigger outbound \
  --condition recipient.domain,is,example.com \
  --action archive

# A policy you can attach to a workspace
nylas agent policy create --name "Strict Policy"
Enter fullscreen mode Exit fullscreen mode

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.

Known limits (free plan)

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

Wrapping up

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.

Top comments (0)