Skip to content
Skip to main content

Give your agent email access

Your agent needs email to communicate with the outside world — sending updates, reading replies, triaging inboxes, extracting data from messages. The Nylas CLI gives your agent full email access across Gmail, Outlook, Exchange, Yahoo, iCloud, and IMAP through simple shell commands that return structured JSON.

Prerequisites

Section titled “Prerequisites”

Make sure the CLI is installed and authenticated. If not, follow the AI agents quickstart first.

nylas auth whoami --json

Read email

Section titled “Read email”

List recent messages. Always pass --json for structured output and --limit to control token consumption.

nylas email list --limit 5 --json

List only unread messages:

nylas email list --unread --limit 10 --json

Read the full content of a specific message:

nylas email read <MESSAGE_ID> --json

Send email

Section titled “Send email”

Send a message on behalf of the connected user. Always pass --yes to skip the confirmation prompt.

nylas email send \
  --to "[email protected]" \
  --subject "Weekly status update" \
  --body "Here are this week's highlights..." \
  --yes

Send with CC and scheduled delivery:

nylas email send \
  --to "[email protected]" \
  --cc "[email protected]" \
  --subject "Meeting notes" \
  --body "Attached are the notes from today's sync." \
  --schedule "tomorrow 9am" \
  --yes

Search email

Section titled “Search email”

Search uses the provider’s native search syntax (Gmail search operators, Microsoft KQL), so queries like from: and has:attachment work as expected.

nylas email search "from:[email protected]" --limit 5 --json
nylas email search "has:attachment subject:invoice" --limit 10 --json

Manage messages

Section titled “Manage messages”
# Mark a message as read
nylas email mark read <MESSAGE_ID>


# Star/flag a message
nylas email mark starred <MESSAGE_ID>


# Delete a message
nylas email delete <MESSAGE_ID> --yes

Example: inbox triage workflow

Section titled “Example: inbox triage workflow”

Here’s a realistic pattern for an agent that triages an inbox:

# 1. Get unread messages
nylas email list --unread --limit 20 --json


# 2. Read the full content of a message that looks important
nylas email read <MESSAGE_ID> --json


# 3. (Agent classifies the message using its LLM)


# 4. Reply to urgent messages
nylas email send \
  --to "[email protected]" \
  --subject "Re: Server outage" \
  --body "Looking into this now. Will update within the hour." \
  --yes


# 5. Mark processed messages as read
nylas email mark read <MESSAGE_ID>

Using MCP instead

Section titled “Using MCP instead”

If your agent supports Model Context Protocol (Claude Code, Cursor, Windsurf, VS Code, Codex CLI), you can register the CLI as an MCP server instead of calling commands directly:

nylas mcp install --assistant claude-code

This gives your agent typed tools for email operations without subprocess calls. See the MCP docs for details.

What’s next

Section titled “What’s next”