Create an AI Agent Email Identity

Prerequisites

Creating an AI agent email identity requires a Nylas API key, the CLI (version 1.x or later), and an authenticated shell session. The full setup takes under 2 minutes when these three pieces are in place. If you haven't configured them yet, the getting started guide walks through dashboard signup, install, and nylas auth config --api-key.

Step 1 — Create the agent account

A Nylas agent account is a managed email identity backed by provider=nylas that can send and receive mail without an OAuth handshake or a third-party mailbox. Creating one takes a single CLI command and produces a grant that behaves like any other connection in the Nylas v3 API.

Pick the local-part you want the agent to use. The domain is your application's *.nylas.email zone, so the final address follows the pattern localpart@appslug.nylas.email. The command completes in under 1 second:

nylas agent account create me@yourapp.nylas.email

The CLI returns three fields confirming the account is live. A successful create looks like this:

✓ Agent account created successfully!

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

Three things happen during this step. The CLI creates a grant with provider=nylas, auto-creates the nylas connector on the application if it doesn't already exist, and stores the new grant locally so subsequent commands resolve it without an explicit --grant. No OAuth handshake is involved — the identity is managed end-to-end by Nylas, sitting on the same grant model as any other connection in the v3 API.

Step 2 — Add an app password for IMAP/SMTP

An app password turns a Nylas agent account into a standard IMAP/SMTP mailbox that any mail client or library can connect to. Without this step, the agent identity can only send and receive through the Nylas API and CLI — adding a password opens the mailbox to protocols like IMAP4rev1 (RFC 3501) and SMTP (RFC 5321).

The password must be 18-40 characters of printable ASCII with at least one uppercase letter, one lowercase letter, and one digit. Attach it with a single update command:

nylas agent account update me@yourapp.nylas.email \
  --app-password 'ValidAgentPass123ABC!'

Per the official agent docs, the password requirements are:

• 18 to 40 characters
• printable ASCII only, with no spaces
• at least one uppercase letter, one lowercase letter, and one digit

Once the password is set, the agent's email address becomes the IMAP/SMTP username and the app password is the credential. Rotate the password at any time by re-running update with a new value — the old credential is revoked immediately.

Step 3 — Send mail from the agent identity

Sending mail from a Nylas agent identity works through the same nylas email send command used for any other grant. When the active grant is provider=nylas, the CLI automatically routes through Nylas's managed transactional path instead of the provider's native SMTP. The sender address is pulled from the active grant, so no --from flag is needed.

According to the Nylas v3 API docs, transactional sends on agent accounts have a per-grant rate limit. The command below sends a plain-text message in under 2 seconds:

nylas email send \
  --to you@example.com \
  --subject "Hello from the agent" \
  --body "This message was sent from a managed agent identity."

Two limits apply to agent sends: GPG signing and encryption are not supported, and stored signatures via --signature-id are not honoured. For richer send patterns — HTML body, attachments, scheduled delivery — see Send email from the terminal.

Step 4 — Read the agent's inbox

Reading mail from a Nylas agent inbox uses the standard nylas email list command. The CLI queries the Nylas v3 Messages API and returns results in either human-readable or JSON format. JSON output with --json is designed for agent loops and shell pipelines where structured data parsing matters.

The --limit flag controls how many messages are returned per call (default is 50, maximum 200 per the Nylas API). Combine it with jq to extract only the fields the agent needs:

# Latest 10 messages
nylas email list --limit 10

# Structured output for an agent or shell pipeline
nylas email list --json | jq '.[] | {from: .from[0].email, subject, date}'

For a long-lived agent process — or a human reading the inbox in a standard mail client — connect over IMAP using the agent email as the username and the app password created in the previous step as the credential.

Step 5 — Confirm with nylas agent status

The nylas agent status command checks three things: whether the nylas connector exists on the application, how many agent accounts are configured, and whether each account's grant is in a valid state. Running the check takes under 1 second and requires no additional flags.

Run this command after creating the agent account and again whenever send or receive operations start failing. The status output is the fastest way to confirm the connector and grant are both healthy:

nylas agent status

A healthy output shows Status: valid for each agent account. If the connector is missing or a grant has expired, the output includes the specific error state — no need to dig through API responses manually.

Limits to know about

Nylas agent accounts share the same grant model as OAuth-based connections, but three constraints are specific to the managed provider=nylas path. Understanding these limits before deploying an agent prevents unexpected failures in production. Each constraint is enforced at the API level, not the CLI level.

• Send rules and inbound filters live on policies. Use nylas agent policy and nylas agent rule to attach outbound caps and inbound rules (auto-archive, mark-as-spam, star VIP senders) to the account. The agent reference covers the full policy and rule API.
• Address shape is fixed at creation. The local-part is yours; the domain is the application's *.nylas.email zone.
• Deleting revokes the grant. nylas agent account delete removes the underlying provider=nylas grant — pass --yes to skip the confirmation prompt.

Next steps

• Stop your AI agent from going rogue — attach a policy and rules to this identity before letting an agent send from it
• Give your AI coding agent an email address — connect Claude Code, Cursor, or Codex to this identity over MCP
• Design email systems for AI agents — structured formats and machine-readable templates the agent can parse reliably
• Agent-to-agent email communication — create two agent accounts and exchange structured JSON messages between them
• Send email from the terminal — full transactional send reference, including HTML, attachments, and scheduling
• Full command reference — every nylas agent flag and subcommand