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:[e-mail]"

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:

Operator	Example	Description
from:	from:[e-mail]	From specific sender
to:	to:me	Sent to specific recipient
subject:	subject:meeting	Subject contains word
has:attachment	has:attachment	Has attachments
is:unread	is:unread	Unread messages
is:starred	is:starred	Starred messages
after:	after:2024/01/01	After specific date
before:	before:2024/12/31	Before specific date
newer_than:	newer_than:2d	Newer than 2 days
older_than:	older_than:1w	Older than 1 week
label:	label:work	Has specific label

Combine operators: from:[e-mail] subject:report has:attachment

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