Getting Started with Agent Accounts

What is a Nylas Agent Account?

Your AI agent needs to send and receive email. Self-hosted email means 5 systems you maintain yourself: DNS MX records (24-48 hours to propagate), an SMTP daemon like Postfix or Exim (12 security advisories since 2020, per the official announcement list), spam filtering via SpamAssassin, TLS certificates rotated quarterly, and a MIME parser for RFC 5322 wire format.

A Nylas Agent Account replaces all 5 with one CLI command. You get a fully managed email identity that sends and receives mail without OAuth credentials, MX records, or a third-party mailbox. The API provisions your address in under 2 seconds and returns a grant — the same entity type used for Gmail, Outlook, and IMAP connections — so every standard email, calendar, and contacts endpoint works identically. Your address lives on the *.nylas.email domain, and the identity plugs into the same Nylas v3 API surface as any OAuth-connected mailbox.

What can an Agent Account do?

An Agent Account gives your agent 3 capabilities on a single identity: email, calendar, and contacts. One grant, one API key, one workspace. Your agent reads its inbox, checks free/busy availability, and creates calendar events — no second service, no separate integration. Competitors like Agentmail, Cloudflare Email Workers, and Postmark provide managed email accounts. None include calendar or contacts endpoints on the same identity.

Every capability uses the same CLI and API surface you already know from OAuth-connected mailboxes. If your agent sends email with nylas email send, it can also run nylas calendar events list and nylas contacts list. No extra setup. No additional credentials. For AI agents connected over MCP, all 36 tools are available through the same server connection.

How do I create an agent account?

Creating an agent account takes one CLI command and completes in under 2 seconds. The command provisions a grant with provider=nylas, auto-creates the managed connector if it doesn't exist, and stores the grant locally so subsequent commands resolve it automatically. No OAuth handshake, no DNS propagation, no dashboard clicks.

The nylas agent account create command accepts the email address you want as its only argument. The domain is your application's *.nylas.email zone. The address is live and ready to send within 2 seconds of the command returning:

nylas agent account create support@yourapp.nylas.email

✓ Agent account created successfully!

Email:      support@yourapp.nylas.email
Provider:   nylas
Status:     valid

Once the account exists, send email with the same nylas email send command used for any other grant. The sender address is pulled from the active grant automatically — no --from flag needed. Delivery completes in under 2 seconds with DKIM signing on the *.nylas.email domain:

nylas email send \
  --to customer@example.com \
  --subject "Your receipt" \
  --body "Order #4821 confirmed. Shipping Tuesday."

Reading the agent's inbox uses nylas email list. Add --json for structured output that agent loops and shell pipelines can parse. The Nylas v3 API returns up to 200 messages per call:

nylas email list --limit 5 --json | jq '.[] | {from: .from[0].email, subject}'

That's a working agent identity — create, send, receive — in 3 commands. For the full walkthrough including app passwords for IMAP/SMTP access, status checks, and production limits, see Create an AI Agent Email Identity.

How is Agent Account architected?

Agent Account is built on a 5-entity chain: Application, Connector, Grant, Workspace, and Policy with Rules. The Application holds API keys, the Connector defines the managed provider type, the Grant is the email identity itself, the Workspace groups policy and rule attachments, and Rules define condition-action pairs that filter inbound and outbound email. A single application can manage hundreds of agent accounts through this chain.

Each entity has a specific role:

• Application — your project-level container. Holds API keys, region settings (US or EU), and all connectors. Created once in the Nylas Dashboard.
• Connector — defines the provider type. For agent accounts, this is the Nylas managed provider. The CLI auto-creates it on the first nylas agent account create call — no manual connector setup needed.
• Grant (Agent Account) — the individual email identity. Has an email address, a status field, and a workspace_id that links to its configuration. Works with every standard email, calendar, and contacts endpoint — the same grant that handles inbox reads also powers nylas calendar events list and availability lookups.
• Workspace — the attachment point for policy and rule configuration. Holds policy_id and rules_ids[] references. This entity is the architectural layer between the identity and its behavioral constraints.
• Policy — defines outbound constraints for the workspace (rate limits, domain restrictions).
• Rules — condition-action pairs. Each rule matches on envelope fields like sender domain or recipient, then fires an action: block, archive, mark_as_read, or mark_as_starred.

What is a workspace and why does it exist?

A workspace sits between your agent account's grant and its policies and rules. Instead of storing policy_id directly in grant settings, the workspace holds both policy_id and rules_ids[] as separate references. Why does this matter? You can rotate policies without touching the grant, manage rules independently from policies, and share configurations across accounts.

Your workspace lives at /v3/workspaces/{id} on the Nylas API. When you create an agent account, the API provisions both the grant and its workspace in a single call — under 2 seconds. You never interact with the workspace directly. When you run nylas agent policy list, the CLI loads your default grant, fetches the workspace, reads the workspace's policy_id, and returns the associated policy. The chain is invisible to you.

Three architectural benefits follow from the indirection:

1. Policy rotation — swap policies by patching the workspace, not the grant. The identity stays stable while behavior changes. Zero downtime, under 200 ms per update.
2. Independent rule management — add or remove rules on the workspace without touching the policy object. The workspace's rules_ids[] array is the authoritative rule list for that account.
3. Multi-tenancy — different accounts can point to the same workspace when they share behavioral constraints, or each can have its own. One application with 50 agent accounts might use 3 workspaces: one for support inboxes, one for notification senders, one for test automation.

Here's where it pays off: your agent is sending customer receipts through a policy that caps outbound volume at 500/hour. Marketing wants to raise the cap for a launch campaign. Without workspaces, you'd patch the grant settings and risk breaking the agent mid-send. With workspaces, you swap the policy on the workspace in one PATCH call. The grant never changes. The agent never restarts. Under 200 ms, zero downtime.

Run nylas agent account get to see the workspace linkage on any agent account. The Workspace ID field connects your identity to its configuration:

nylas agent account get me@yourapp.nylas.email

Email:        me@yourapp.nylas.email
Provider:     nylas
Status:       valid
Workspace ID: ws_abc123

How does inbound email reach an agent account?

Someone sends email to your agent's *.nylas.email address. The message enters Nylas's managed mail infrastructure, resolves to your grant by email address, loads your workspace, and evaluates rules in priority order. If no rule blocks it, the message lands in the inbox. The full path from external sender to delivered message completes in under 3 seconds for 95% of messages.

The inbound path has 4 stages:

1. MX resolution — Nylas manages the *.nylas.email MX records. The sending server connects to Nylas's mail infrastructure, not yours. No DNS configuration on your side.
2. Grant lookup — the message's recipient address is matched to the corresponding grant. Each agent address maps to exactly one grant.
3. Policy / Rules evaluation — the grant's workspace is loaded, and the policy and each rule in rules_ids[] are evaluated by priority. Rules match on envelope fields: sender domain, sender address, subject line.
4. Delivery or block — if a rule fires block, the message is rejected. Otherwise, it lands in the inbox and triggers any registered message.created webhooks.

How does outbound email leave an agent account?

Your agent calls nylas email send or hits the v3 Messages API. The request resolves your active grant, loads the workspace, evaluates your outbound policy, and routes the message through Nylas's transactional send pipeline. Two seconds from grant resolution to the recipient's mail server.

The outbound path has 4 stages:

1. Grant resolution — the CLI resolves the active agent account grant. The sender address is pulled from the grant automatically — no --from flag needed.
2. Workspace lookup — the grant's workspace_id is fetched. The workspace holds the policy and rules that govern outbound behavior.
3. Policy / Rules evaluation — outbound constraints and rules are checked. If the policy restricts the recipient domain, a rule blocks the send, or the send rate exceeds limits, the request is rejected before it reaches SMTP.
4. Transactional send — Nylas signs the message with DKIM for the *.nylas.email domain and delivers it to the recipient's mail server. A message.send_success webhook fires on delivery.

Why does Agent Account replace self-hosted email?

Self-hosted email demands 5 separate systems, each carrying maintenance and security overhead. According to Postfix's official announcement list, the most popular open-source MTA published 12 security advisories since 2020. Every advisory means a patch, a restart, and a smoke test. Agent Account replaces all 5 systems with one API call that provisions a working mailbox in under 2 seconds.

The architectural difference is that Agent Account pushes mail infrastructure behind an API boundary. You don't manage daemons, certificates, or DNS records — you call an endpoint. Policy and rule enforcement happens at the workspace layer before messages touch SMTP, so a prompt injection targeting an AI agent cannot bypass the constraints. For the full containment pattern, see Stop Your AI Agent From Going Rogue.

Agent accounts also support custom domains — you can send and receive from your own domain instead of *.nylas.email. For quick prototyping and test automation, the managed domain works out of the box. When you're ready for production branding, configure your custom domain through the Nylas Dashboard.

Next steps

• Create an AI Agent Email Identity — hands-on walkthrough: create an account, add an app password, send and receive in 2 minutes
• Agent Rules and Policies: Complete Guide — every trigger, condition, operator, action, and policy setting with real-world examples
• Stop Your AI Agent From Going Rogue — attach a containment policy and rules to the workspace before letting an agent send
• Give Your AI Coding Agent an Email Address — connect Claude Code, Cursor, or Codex to an agent identity over MCP
• Receive Email Without an SMTP Server — webhooks, real-time processing, and per-test isolated inboxes
• Agent-to-Agent Email Communication — create two agent accounts and exchange structured JSON between them
• Best Email Infrastructure for AI Agents — compare Agent Accounts, provider APIs, IMAP, SMTP, MCP, and CLI tools
• Full command reference — every nylas agent flag and subcommand
• Nylas v3 API documentation — the API surface that Agent Account grants plug into