Skip to content
Skip to main content

Give your agent contacts access

Your agent needs contacts access to look up people by name or email, enrich context before sending messages, and manage address books on behalf of users. The Nylas CLI gives your agent access to contacts across Gmail, Outlook, Exchange, and iCloud through 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

Search contacts

Section titled “Search contacts”

Find contacts by name or email. This is the most common operation — look someone up before sending an email or scheduling a meeting.

nylas contacts search --query "Alice" --json
nylas contacts search --query "[email protected]" --json

List contacts

Section titled “List contacts”

List all contacts for the connected user.

nylas contacts list --limit 10 --json

View contact details

Section titled “View contact details”

Get the full details for a specific contact — emails, phone numbers, company, job title.

nylas contacts show <CONTACT_ID> --json

Create a contact

Section titled “Create a contact”

Add a new contact to the user’s address book.

nylas contacts create --name "Bob Smith" --email "[email protected]"

List contact groups

Section titled “List contact groups”

See how contacts are organized (labels in Gmail, folders in Outlook).

nylas contacts groups list --json

Example: enrich context before sending email

Section titled “Example: enrich context before sending email”

A common agent pattern — look up the recipient before composing a message:

# 1. Search for the contact
nylas contacts search --query "[email protected]" --json


# 2. (Agent uses contact details like company, title, and
#     recent interactions to personalize the email)


# 3. Send a personalized email
nylas email send \
  --to "[email protected]" \
  --subject "Following up on our conversation" \
  --body "Hi Alice, great talking with you at the conference..." \
  --yes

Using MCP instead

Section titled “Using MCP instead”

If your agent supports Model Context Protocol (Claude Code, Cursor, Windsurf, VS Code, Codex CLI), register the CLI as an MCP server for typed contact tools:

nylas mcp install --assistant claude-code

See the Nylas MCP server docs for details.

What’s next

Section titled “What’s next”