mail

What this skill does

# Mail CLI Skill

Use mail-cli tool to interact with Gmail.

## Command Prefix

All commands use `uv run`:

```bash
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

```bash
# 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

```bash
# 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:[email protected]"
```

### List Unread Emails

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:[email protected]` | 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:[email protected] subject:report has:attachment`

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