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.
One-time setup
If you've never touched the CLI before:
brew install nylas/nylas-cli/nylas
# or, without Homebrew:
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.
Creating accounts
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:
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:
Discovery and health checks
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 [email protected] # 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 "[email protected]" --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.
Daily driving the mailbox
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 "[email protected]" \
--cc "[email protected]" \
--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 "[email protected],[email protected]" \
--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.
Governance from the terminal
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.
Teardown
Ephemeral identities only make sense if destruction is as cheap as creation:
Delete by email or by grant ID; --yes skips the confirmation so it's scriptable.
When something breaks
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.
Where this beats the dashboard
The dashboard is fine for a first look. The CLI wins everywhere else:
CI and scripts. Provision a mailbox in a pipeline, run a test against it, delete it. No API client code, no session cookies.
Repeatability. Acreatecommand in a setup script is documentation; a sequence of dashboard clicks isn't.
Agent-friendliness. An AI agent can run these commands itself. The structured--jsonoutput and non-interactive--yesflag exist precisely so an autonomous process never hangs on a prompt.
Credential extraction.nylas auth tokenprints the raw API key andnylas auth whoami --jsongives you the grant ID — two commands and your.envis 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 [email protected], 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.