There's a specific kind of friction in provisioning infrastructure through a web UI: you're building an automated system, but step one is clicking through a dashboard. For email identities that your code creates, monitors, and tears down, the browser is the wrong tool. The Nylas CLI closes that gap — every part of an Agent Account's lifecycle is a terminal command.
Agent Accounts (currently in beta) are hosted mailboxes with real addresses that your application owns end-to-end. They send, receive, and hold calendar events like any human account, and the quickstart gets you from API key to working mailbox in under 5 minutes. Here's how to do all of it without leaving the shell.
If you've never touched the CLI before:
brew install nylas/nylas-cli/nylas
curl -fsSL https://cli.nylas.com/install.sh | bash
nylas init
nylas init
opens a browser once for account creation and sign-in — the only step that needs a human. After that, verify with nylas auth whoami --json
, which returns your active grant, provider, and status as parseable JSON. If you already have an API key, skip the browser entirely with nylas init --api-key <NYLAS_API_KEY>
(add --region eu
for EU data residency).
Want to confirm the binary works before wiring up credentials? nylas demo email list
returns sample data with no authentication at all — useful in provisioning scripts that should fail fast if the install step broke.
With a domain registered (either your own with MX and TXT records, or a *.nylas.email
trial subdomain for instant testing), creation is one line:
nylas agent account create agent@yourdomain.com
The CLI prints the new grant ID plus status and connector details. That grant ID is the handle for everything else — messages, calendar, webhooks.
Want a human to supervise the mailbox from Outlook or Apple Mail? Create it with IMAP/SMTP access enabled:
nylas agent account create agent@yourdomain.com --app-password "MySecureP4ssword!2024"
Three commands cover the "what do I have and is it working" questions:
nylas agent account list --json # every Agent Account on the application
nylas agent account get agent@yourdomain.com # one account, by ID or email
nylas agent status --json # connector readiness
Accounts also show up in nylas auth list
with Provider: Nylas
, side by side with any OAuth-connected grants. Switch between them with nylas auth switch
, and the regular email and calendar commands operate on whichever is active:
nylas email list --limit 5 --json
nylas email send --to "you@example.com" --subject "Hi" --body "From the agent." --yes
nylas calendar events list --days 7 --json
Note the flags. The autonomous agents guide is blunt about this: always pass --json
for parseable output, always pass --yes
on sends and deletes so nothing blocks on a confirmation prompt, and always pass --limit
(start with 5) so list commands don't flood whatever's consuming the output.
Once an account exists, the everyday email commands go well beyond list-and-send. Search, read a specific message, and even schedule delivery for later:
nylas email search "meeting agenda" --limit 5 --json
nylas email read <MESSAGE_ID> --json
nylas email send \
--to "alice@example.com" \
--cc "bob@example.com" \
--subject "Project update" \
--body "Status report attached." \
--schedule "tomorrow 9am" \
--yes
The calendar side has a similar range — list events, create them with explicit timestamps, or find a slot that works for multiple people:
nylas calendar find-time \
--participants "alice@example.com,bob@example.com" \
--duration 30m \
--json
nylas calendar schedule ai "Find 30 minutes with Alice next week"
That last one is natural-language scheduling: you hand it a sentence, it works out the slot. All of these operate on whichever grant is active, so they work identically against an Agent Account and a human's OAuth-connected mailbox.
Policies and rules — the guardrails that control send limits, spam handling, and inbound filtering — are inspectable the same way:
nylas agent policy list
nylas agent rule list
And webhooks, so your code reacts to inbound mail in real time:
nylas webhook triggers # see what you can subscribe to
nylas webhook create \
--url https://youragent.example.com/webhooks/nylas \
--triggers "message.created,message.updated"
nylas webhook list
These work against any grant, connected or agent-owned.
Ephemeral identities only make sense if destruction is as cheap as creation:
nylas agent account delete agent@yourdomain.com --yes
Delete by email or by grant ID; --yes
skips the confirmation so it's scriptable.
The failure modes are predictable enough to script around. The autonomous agents guide ships a troubleshooting table; here's the short version:
| Symptom | Fix |
|---|---|
nylas: command not found |
|
Re-run the install, or use the full path (/opt/homebrew/bin/nylas ) |
|
error.type: "unauthorized" |
|
Run nylas dashboard apps apikeys create to mint a new API key |
|
not_found_error on a grant |
|
Run nylas auth login to reconnect |
|
rate_limit_error |
|
| Back off and retry | |
| Commands hang | You forgot --yes on a send or delete |
| Empty results | |
nylas auth list to check accounts, nylas auth switch to change |
Errors come back in the same JSON envelope as the API — a request_id
plus an error
object with type
and message
— so a script can branch on error.type
instead of grepping prose.
The dashboard is fine for a first look. The CLI wins everywhere else:
create
command in a setup script is documentation; a sequence of dashboard clicks isn't.--json
output and non-interactive --yes
flag exist precisely so an autonomous process never hangs on a prompt.nylas auth token
prints the raw API key and nylas auth whoami --json
gives you the grant ID — two commands and your .env
is populated.There's also an escape hatch in both directions. Everything the CLI does maps to plain API calls (account creation is POST /v3/connect/custom
with "provider": "nylas"
), so you can graduate to SDK code whenever a script outgrows the shell. And if your editor or agent speaks MCP, nylas mcp install
registers 16 email, calendar, and contacts tools so you skip subprocess calls entirely.
Next step: register a trial domain, run nylas agent account create test@your-application.nylas.email
, and send yourself a message from it. Total elapsed time should be a coffee refill. Then check nylas agent status --json
and see what a healthy connector looks like before you build anything on top.