# Quickstart: Autonomous AI agents

Source: https://developer.nylas.com/docs/v3/getting-started/cli-for-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](/docs/v3/getting-started/coding-agents/) instead.

> **Info:** 
> **Install the Nylas skill for faster setup.** The [`nylas-cli` skill](https://github.com/nylas/skills) 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`.

> **Info:** 
> **The Nylas docs are built for agents.** When you need API details the CLI doesn't expose, fetch them directly:
> 
> - **[`llms.txt`](https://developer.nylas.com/llms.txt)** -- curated sitemap of every key page. Start here.
> - **[`llms-full.txt`](https://developer.nylas.com/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](/docs/v3/getting-started/agent-email/) and [Share your calendar with your agent](/docs/v3/getting-started/agent-calendar/).
- **Give the agent its own inbox and calendar.** The agent has a dedicated `agent@yourdomain.com` 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](/docs/v3/getting-started/agent-own-email/) and [Give your agent its own calendar](/docs/v3/getting-started/agent-own-calendar/). These run on [Nylas Agent Accounts](/docs/v3/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:

```bash
nylas auth whoami --json
```

If this returns JSON with `email`, `provider`, `grant_id`, and `status`, you're ready. Skip to [Step 4](#step-4-verify-and-start-using).

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:

```bash
brew install nylas/nylas-cli/nylas
```

If Homebrew is not available:

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

Verify the install worked:

```bash
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:

```bash
nylas init --api-key <NYLAS_API_KEY>
```

For EU data residency:

```bash
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:

```bash
nylas auth whoami --json
```

**Expected output:**

```json
{
  "email": "user@example.com",
  "provider": "google",
  "grant_id": "d3f4a5b6-c7d8-9e0f-a1b2-c3d4e5f6g7h8",
  "status": "valid"
}
```

If you need the raw API key for any reason:

```bash
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:

```bash
nylas email list --limit 3 --json
```

**Expected output** (a flat JSON array):

```json
[
  {
    "id": "msg_abc123",
    "subject": "Learn how to Send Email with Nylas APIs",
    "from": [{ "name": "Nylas DevRel", "email": "nylasdev@nylas.com" }],
    "to": [{ "name": "Nyla", "email": "nyla@nylas.com" }],
    "snippet": "Send Email with Nylas APIs",
    "date": 1706811644,
    "unread": true,
    "folders": ["INBOX", "UNREAD"]
  }
]
```

**If this returns an error**, check `error.type`:

```json
{
  "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](https://modelcontextprotocol.io/) (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:

```bash
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

```bash
# 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 "recipient@example.com" \
  --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 "alice@example.com" \
  --cc "bob@example.com" \
  --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](/docs/v3/agent-accounts/email-threading/) for the details.

### Calendar commands

```bash
# 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 "alice@example.com,bob@example.com" \
  --duration 30m \
  --json

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

### Contacts commands

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

### Agent Account commands

For agents that need their own Nylas-hosted `agent@yourdomain.com` mailbox. Requires a [domain registered with Nylas](/docs/v3/agent-accounts/provisioning/).

```bash
# Create an Agent Account (returns the grant ID)
nylas agent account create agent@yourdomain.com

# Create with IMAP/SMTP access enabled
nylas agent account create agent@yourdomain.com --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 agent@yourdomain.com

# 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 agent@yourdomain.com --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](/docs/v3/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.

```bash
# 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](/docs/v3/notifications/) for payload schemas and signature verification.

### Account commands

```bash
# 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:

```bash
# 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](https://github.com/nylas/cli) -- source code, issues, and releases
- [CLI command reference](https://cli.nylas.com/docs/commands) -- every command and flag documented
- [CLI guides](https://cli.nylas.com/guides) -- 85+ step-by-step guides for email, calendar, MCP, and more
- [Build an LLM agent with email tools](https://cli.nylas.com/guides/build-email-agent-cli) -- wire CLI commands into an agent loop with OpenAI-compatible tool definitions
- [Give agents email via MCP](https://cli.nylas.com/guides/ai-agent-email-mcp) -- full MCP setup guide
- [Audit agent activity](https://cli.nylas.com/guides/audit-ai-agent-activity) -- track actions with source detection and compliance exports