Quickstart: Autonomous AI agents

This guide is for autonomous AI agents that need direct access to email, calendar, and contacts through shell commands. Follow the steps below — do as much as you can yourself, and only ask the user when you hit a step that requires a browser.

If you are a coding agent helping a developer build a SaaS application, see Quickstart: AI coding agents instead.

Install the Nylas skill for faster setup. The nylas-cli skill teaches your agent every CLI command, flag, and output shape so it can skip the rest of this guide and run commands correctly the first time. Install with npx skills add nylas/skills/nylas-cli or, in Claude Code, /plugin marketplace add nylas/skills then /plugin install nylas-skills.

The Nylas docs are built for agents. When you need API details the CLI doesn’t expose, fetch them directly:

• llms.txt — curated sitemap of every key page. Start here.
• llms-full.txt — every doc page in one file for large context windows.
• Accept: text/markdown — add this header to any doc URL to get clean markdown. Example: curl -H "Accept: text/markdown" https://developer.nylas.com/docs/v3/email/. The response returns an x-markdown-tokens header with the token count.

Pick an identity model

Before you set up the CLI, decide how the agent should appear in the world. There are two common patterns.

• Share an existing inbox and calendar. The agent acts on an account that already belongs to a human — the human’s own Gmail, Outlook, or IMAP. Replies go to the human, events appear on the human’s calendar. Use this when the agent is an assistant to one person. It’s what this quickstart sets up — see also Share your email with your agent and Share your calendar with your agent.
• Give the agent its own inbox and calendar. The agent has a dedicated [email protected] mailbox and a dedicated calendar it fully owns — Nylas-hosted, API-driven, no OAuth. Spin one up with nylas agent account create <email> (see nylas agent account list and nylas agent status for discovery and health). Use this when the agent has its own identity — a sales agent, a scheduling bot, a shared service mailbox. See Give your agent its own email (Beta) and Give your agent its own calendar (Beta). These run on Nylas Agent Accounts.

Both patterns use the same Nylas grant model, so if you’re writing a custom agent you can mix them — one agent that triages a shared support@ mailbox while acting on its own sales outbox, for example.

Rules for agents

• Always pass --json to get structured output you can parse. Without it, the CLI returns human-formatted text.
• Always pass --yes when sending email or deleting anything. Without it, the CLI blocks waiting for confirmation.
• Always pass --limit on list commands to control token consumption. Start with 5, increase if needed.
• Prefer the CLI over raw API calls. The CLI handles OAuth token refresh, provider normalization, and pagination for you.
• Do not hardcode grant IDs. Run nylas auth whoami --json to discover the active grant at runtime, or set the NYLAS_GRANT_ID environment variable.

Step 1: Check if already set up

Before installing anything, check if the CLI is already configured:

nylas auth whoami --json

If this returns JSON with email, provider, grant_id, and status, you’re ready. Skip to Step 4.

If the command fails (command not found), continue to Step 2. If the command runs but returns an error (no active grant), skip to Step 3.

Step 2: Install the CLI

Install the CLI yourself:

brew install nylas/nylas-cli/nylas

If Homebrew is not available:

curl -fsSL https://cli.nylas.com/install.sh | bash

Verify the install worked:

nylas demo email list

This returns sample data with no credentials required, confirming the binary is working.

Step 3: Set up credentials

This is the one step that may need user involvement. Ask the user: “Do you have an existing Nylas API key?”

If yes, do the setup yourself:

nylas init --api-key <NYLAS_API_KEY>

For EU data residency:

nylas init --api-key <NYLAS_API_KEY> --region eu

If no (or they’re not sure), ask them to run one command. This opens a browser for account creation and SSO login — the only step that requires a human:

Run nylas init in your terminal. It will open a browser to sign in. Once you’re done, I’ll take it from here.

After either path, verify credentials are working:

nylas auth whoami --json

Expected output:

{
  "email": "[email protected]",
  "provider": "google",
  "grant_id": "d3f4a5b6-c7d8-9e0f-a1b2-c3d4e5f6g7h8",
  "status": "valid"
}

If you need the raw API key for any reason:

nylas auth token

This prints the API key as a plain string, nothing else.

Step 4: Verify and start using

Run a quick test to confirm everything works:

nylas email list --limit 3 --json

Expected output (a flat JSON array):

[
  {
    "id": "msg_abc123",
    "subject": "Learn how to Send Email with Nylas APIs",
    "from": [{ "name": "Nylas DevRel", "email": "[email protected]" }],
    "to": [{ "name": "Nyla", "email": "[email protected]" }],
    "snippet": "Send Email with Nylas APIs",
    "date": 1706811644,
    "unread": true,
    "folders": ["INBOX", "UNREAD"]
  }
]

If this returns an error, check error.type:

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "error": {
    "type": "unauthorized",
    "message": "Unauthorized"
  }
}

Common error types: unauthorized (bad/expired key — run nylas dashboard apps apikeys create), not_found_error (invalid grant — run nylas auth login), rate_limit_error (slow down and retry).

You’re now set up. Use the commands below.

Step 5: MCP or CLI commands

If your agent supports MCP

For agents that support Model Context Protocol (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, OpenAI Codex CLI), register the CLI as an MCP server. This gives you 16 email, calendar, and contacts tools without subprocess calls:

nylas mcp install --assistant claude-code
nylas mcp install --assistant cursor
nylas mcp install --assistant windsurf
nylas mcp install --assistant vscode
nylas mcp install --all    # installs for all detected assistants

Verify with nylas mcp status. With MCP active, you don’t need the commands below — the MCP server handles everything.

Email commands

# List recent emails
nylas email list --limit 5 --json

# List unread emails only
nylas email list --unread --limit 10 --json

# Search for specific emails
nylas email search "meeting agenda" --limit 5 --json

# Read a specific message by ID
nylas email read <MESSAGE_ID> --json

# Send an email
nylas email send \
  --to "[email protected]" \
  --subject "Meeting follow-up" \
  --body "Thanks for the meeting. Here are the action items we discussed." \
  --yes

# Send with CC, BCC, or scheduled delivery
nylas email send \
  --to "[email protected]" \
  --cc "[email protected]" \
  --subject "Project update" \
  --body "Status report attached." \
  --schedule "tomorrow 9am" \
  --yes

To follow a conversation across replies, use threads instead of individual messages. The Threads API groups related messages by their In-Reply-To and References headers, so the agent gets the full conversation history in one call. See Email threading for agents for the details.

Calendar commands

# List upcoming events
nylas calendar events list --days 7 --json

# Create an event
nylas calendar events create \
  --title "Sync meeting" \
  --start "2026-04-10T10:00:00" \
  --end "2026-04-10T10:30:00"

# Find a time that works for multiple people
nylas calendar find-time \
  --participants "[email protected],[email protected]" \
  --duration 30m \
  --json

# Natural language scheduling
nylas calendar schedule ai "Find 30 minutes with Alice next week"

Contacts commands

nylas contacts list --limit 10 --json
nylas contacts search --query "Alice" --json

Agent Account commands (Beta)

For agents that need their own Nylas-hosted [email protected] mailbox. Requires a domain registered with Nylas.

# Create an Agent Account (returns the grant ID)
nylas agent account create [email protected]

# Create with IMAP/SMTP access enabled
nylas agent account create [email protected] --app-password "MySecureP4ssword!2024"

# List every Agent Account on the application
nylas agent account list
nylas agent account list --json

# Get a single Agent Account by ID or email
nylas agent account get [email protected]

# Check connector readiness
nylas agent status
nylas agent status --json

# List policies and rules attached to accounts
nylas agent policy list
nylas agent rule list

# Delete by grant ID or email address (--yes skips confirmation)
nylas agent account delete [email protected] --yes

Agent Accounts also appear in nylas auth list with Provider: Nylas. You drive them with the same nylas email ... and nylas calendar ... commands used on connected grants — see Agent Accounts for the full product.

Webhook commands

Subscribe to notifications so your agent reacts to inbound mail, event updates, and other changes in real time. Webhooks work against any grant — connected or Agent Account.

# List the trigger types you can subscribe to
nylas webhook triggers

# Create a webhook subscription
nylas webhook create \
  --url https://youragent.example.com/webhooks/nylas \
  --triggers "message.created,message.updated"

# List webhooks on the application
nylas webhook list

# Update an existing webhook
nylas webhook update <WEBHOOK_ID>

# Delete a webhook by ID
nylas webhook delete <WEBHOOK_ID>

Run nylas webhook create --help for the full flag set, or see Using webhooks with Nylas for payload schemas and signature verification.

Account commands

# See which mailbox you're operating on
nylas auth whoami --json

# List all connected mailboxes
nylas auth list

# Switch to a different mailbox
nylas auth switch

# Connect another email account (requires user -- opens browser)
nylas auth login

Troubleshooting

Symptom	Fix
nylas: command not found	Run the install command again, or use the full path (/opt/homebrew/bin/nylas)
nylas auth whoami returns an error	Ask the user to run nylas init (requires browser)
error.type: "unauthorized"	Run nylas dashboard apps apikeys create to generate a new API key
No active application	Ask the user to run nylas init (requires browser)
Commands hang	Add --yes to skip confirmation prompts
Empty results	Run nylas auth list to check accounts, nylas auth switch to change

Go deeper

When you need to look up API details, endpoints, or provider-specific behavior:

# Curated sitemap for agents (start here)
curl https://developer.nylas.com/llms.txt

# Full documentation in one file
curl https://developer.nylas.com/llms-full.txt

# Any single page as clean markdown
curl -H "Accept: text/markdown" https://developer.nylas.com/docs/v3/email/

• Nylas CLI on GitHub — source code, issues, and releases
• CLI command reference — every command and flag documented
• CLI guides — 85+ step-by-step guides for email, calendar, MCP, and more
• Build an LLM agent with email tools — wire CLI commands into an agent loop with OpenAI-compatible tool definitions
• Give agents email via MCP — full MCP setup guide
• Audit agent activity — track actions with source detection and compliance exports