Guide

Create an AI Agent Email Identity

Your AI agent needs a real email address — one it can send from and receive at — without you spinning up a Gmail tenant just for it. Nylas agent accounts give you a managed identity backed by provider=nylas: no OAuth handshake, no third-party mailbox, no Workspace seat. Setup is two commands, and the result is an inbox the agent owns.

Written by Pouya Sanooei Software Engineer

Prerequisites

You need a Nylas API key, the CLI installed, and an authenticated shell. If you haven't set those up yet, the getting started guide walks through dashboard signup, install, and nylas auth config --api-key.

Step 1 — Create the agent account

Pick the local-part you want the agent to use, then create the account. The domain is your application's *.nylas.email zone:

nylas agent account create me@yourapp.nylas.email

You should see something like this:

✓ Agent account created successfully!

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

Three things happen here. 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. There is no OAuth handshake — 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

At this point the identity exists but has no IMAP/SMTP credentials. To let a standard mail client or any IMAP library connect to the inbox, attach an app password:

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

Per the official agent docs, the value must be:

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

Once set, the agent's email becomes the IMAP/SMTP username and the app password is the credential. Rotate it later by re-running update with a new value.

Step 3 — Send mail from the agent identity

When the active grant is provider=nylas, nylas email send automatically routes through the managed transactional path. The sender address is taken from the active grant:

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

Two limits on this path: 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

The same command surface works in reverse. List recent messages, then drop into JSON for the agent loop:

# 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 normal mail client — connect over IMAP using the agent email as the username and the app password from Step 2 as the credential.

Step 5 — Confirm with nylas agent status

Before wiring this into an automation loop, verify the connector and accounts are healthy:

nylas agent status

The output reports whether the nylas connector is available, whether agent accounts already exist on the application, and which managed accounts are configured. Run this on first setup and again any time send or receive starts failing — it's the fastest signal that something is off.

Limits to know about

  • 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