mail

name: mail description: Interact with Gmail - list, read, search emails and download attachments. Use when user asks about emails, inbox, or mail-related tasks. user-invocable: true disable-model-invocation: false allowed-tools: Bash, Read

Mail CLI Skill

Use mail-cli tool to interact with Gmail.

Command Prefix

All commands use uv run:

cd ${CLAUDE_PLUGIN_ROOT}/src && uv run mail-cli <command>

First-time Setup

Before using mail-cli, you need to:

1. Create OAuth2 credentials in Google Cloud Console
2. Download the credentials JSON file
3. Save it as ~/.config/mail-cli/credentials.json
4. Run mail-cli auth to authenticate

Commands Reference

Authentication

# Authenticate with Gmail (opens browser)
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run mail-cli auth

# Authenticate in headless/remote mode (manual code entry)
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run mail-cli auth --console

List Emails

# List recent 20 emails
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run mail-cli list

# List specific number of emails
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run mail-cli list -n 10

# List with search query
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run mail-cli list -q "from:someone@example.com"

List Unread Emails

# List unread emails (default 20)
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run mail-cli unread

# List specific number of unread emails
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run mail-cli unread -n 5

Read Email

# Read email by ID
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run mail-cli read <message_id>

# Read email and show HTML content
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run mail-cli read <message_id> --html

# Read and mark as read
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run mail-cli read <message_id> --mark-read

Search Emails

# Search emails
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run mail-cli search -q "subject:important"

# Search with result limit
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run mail-cli search -q "has:attachment" -n 10

Download Attachments

# List attachments in an email
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run mail-cli attachments <message_id>

# Download all attachments
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run mail-cli attachments <message_id> --all

# Download specific attachment by index
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run mail-cli attachments <message_id> --index 1

# Download to specific directory
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run mail-cli attachments <message_id> --all -o ./downloads

Mark Read/Unread

# Toggle read/unread status
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run mail-cli mark <message_id>

Request Mapping

When user requests:

1. "Check my emails" → Use list command
2. "Do I have new emails?" → Use unread command
3. "Read this email" → Use read <message_id> command
4. "Search for emails from..." → Use search -q "from:..." command
5. "Download attachments" → Use attachments <message_id> --all command
6. "Mark as read/unread" → Use mark <message_id> command

Gmail Search Query Syntax

Common search operators:

Combine operators: from:john@example.com subject:report has:attachment

$ARGUMENTS contains the user's specific request. Parse it to determine which command to run.