Skip to content
Skip to main content

Share your email with your agent

Give your agent full read/write access to the inbox you already use — a personal Gmail, a shared Outlook mailbox, or any IMAP account. Messages the agent sends come from your address, and replies land in your inbox. The Nylas CLI handles provider auth and returns structured JSON so your agent can drive every operation from shell commands.

If you’d rather the agent have its own dedicated mailbox (so replies don’t clutter your inbox), see Give your agent its own email.

Prerequisites

Section titled “Prerequisites”

Make sure the CLI is installed and authenticated against the account you want to share. 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”