# Email Copilot

> Check, read, label, archive, and manage emails across multiple accounts. Use when asked to check inbox, read emails, clean up mail, or handle email-related tasks.

- Skill: `leechael/email-copilot` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add leechael/email-copilot`
- Raw SKILL.md: https://api.skillmd.com/api/skills/leechael/email-copilot/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: Leechael (https://skillmd.com/u/leechael)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/leechael/email-copilot

---


## Critical Rules

1. **ALWAYS** read `.claude/skills/email-copilot/rules.md` before processing ANY emails
2. **ALWAYS** run `date` to get current time before processing (for expiry checks, age calculations)
3. **NEVER** mix email IDs between accounts - IDs are account-specific
4. **ALWAYS** use label names (e.g., "Finance/Receipts"), never internal IDs (e.g., "Label_6")
5. **CHECK** `account` field in output before operations
6. **LOG** all user-confirmed actions to `.claude/skills/email-copilot/action-log.md` — **IMMEDIATELY in the same tool call batch as execution, NOT after**
7. **AUTH EXPIRED**: If any command returns `"status": "auth_expired"`, **stop processing that account** and tell the user to run the command shown in the `command` field in their terminal. Do NOT attempt to run `--auth` yourself — it requires interactive browser login

## CLI Alias

All commands use this base (define once per session):
```bash
EMAIL="uv run --project .claude/skills/email-copilot python .claude/skills/email-copilot/scripts/email_cli.py"
GMAIL="uv run --project .claude/skills/email-copilot python .claude/skills/email-copilot/gmail_client.py"
```

## Quick Reference

```bash
# Accounts
$GMAIL --check                    # Check setup status
$GMAIL --auth <name>              # Add/authenticate account
$EMAIL accounts                   # List accounts

# List & Read
$EMAIL [-a ACCOUNT] list [-n LIMIT] [-q QUERY]
$EMAIL [-a ACCOUNT] read <msg_id>

# Actions
$EMAIL [-a ACCOUNT] trash '<json_id_list>'
$EMAIL [-a ACCOUNT] untrash '<json_id_list>'
$EMAIL [-a ACCOUNT] move <label> '<json_id_list>' [-r] [-c]

# Labels
$EMAIL [-a ACCOUNT] labels list
$EMAIL [-a ACCOUNT] labels create "Name"
$EMAIL [-a ACCOUNT] labels delete "Name"
$EMAIL [-a ACCOUNT] labels rename "Old" "New"

# Send & Reply
$EMAIL [-a ACCOUNT] send --to EMAIL --subject SUBJ --body BODY [--cc CC] [--attachment FILE]
$EMAIL [-a ACCOUNT] reply <msg_id> --body BODY [--cc CC]

# Drafts
$EMAIL [-a ACCOUNT] drafts list
$EMAIL [-a ACCOUNT] drafts create --to EMAIL --subject SUBJ --body BODY
$EMAIL [-a ACCOUNT] drafts reply <msg_id> --body BODY
$EMAIL [-a ACCOUNT] drafts send <draft_id>
$EMAIL [-a ACCOUNT] drafts delete <draft_id>

# Attachments
$EMAIL [-a ACCOUNT] attachments <msg_id>
$EMAIL [-a ACCOUNT] download <msg_id> [-o DIR] [-f FILTER]
$EMAIL [-a ACCOUNT] search-download -q QUERY [-o DIR] [-n LIMIT]

# Filters & Maintenance
$EMAIL [-a ACCOUNT] filters list
$EMAIL [-a ACCOUNT] filters add [--from X] [--add-label Y] [--archive] [--mark-read]
$EMAIL [-a ACCOUNT] summary <label> [-n LIMIT]
$EMAIL [-a ACCOUNT] cleanup <label> [-d DAYS]
```

## Procedure

1. **Check Accounts**: `$GMAIL --check` (verifies tokens are valid with real API call)
   - If any account shows `"authenticated": false`, tell user to run: `cd .claude/skills/email-copilot && uv run python gmail_client.py --auth <name>`
   - Do NOT proceed with that account until user confirms re-auth is done
2. **Load Rules**: Read `.claude/skills/email-copilot/rules.md` (MANDATORY)
3. **Review Action Log**: Read `.claude/skills/email-copilot/action-log.md` to identify patterns from recent decisions
4. **Process Each Account**:
   - `$EMAIL -a <account> list -n 100`
   - Apply account-appropriate rules (work: strict cleanup; personal: conservative)
5. **Classify & Execute**:
   - Auto-Trash List matches → `trash`
   - Expired notifications → `trash`
   - Receipts/Statements → `move` to Finance labels
6. **Log Actions**: When user confirms, execute operations AND update `action-log.md` **in the same tool call batch** (parallel Edit + Bash calls)
7. **Report & Evolve**:
   - Group remaining by account AND category
   - Review action log for recurring patterns → propose rule updates
   - Update `rules.md` if user agrees

## Learning & Evolution

When email doesn't match rules:
- **Cold sales** → Propose adding sender to Auto-Trash List
- **New project** → Propose adding Project Keyword
- **Recurring newsletter** → Propose Newsletter category

Always ask user before updating `rules.md`.

## Multi-Account Notes

- Work accounts: Prioritize project emails, strict cleanup
- Personal accounts: Conservative deletions, preserve receipts
- Each operation outputs `account` field to identify mailbox

## Tips

- **Reply-To**: `reply` uses Reply-To header when present (mailing lists)
- **GitHub**: Check snippet for "approved", "lgtm", bot names
- **Safety**: If unsure, list in report instead of trashing
- **Drafts Workflow**: Create draft → User reviews in Gmail → `drafts send` or manual send

## Action Log Format

Log file: `.claude/skills/email-copilot/action-log.md`

```markdown
## YYYY-MM-DD

### Trashed
- [account] sender@example.com - "Subject" (reason: auto-trash match / user confirmed)

### Moved
- [account] sender@example.com - "Subject" → Label/Name

### Kept
- [account] sender@example.com - "Subject" (user decision: reason)

### Patterns Identified
- sender@example.com appeared 3x this week → consider adding to auto-trash
```

Review log before each session to:
1. Identify senders appearing repeatedly → propose Auto-Trash rule
2. Find emails consistently moved to same label → propose filter
3. Track user overrides → adjust rule confidence

## Additional Files

- **First-time setup**: Read `.claude/skills/email-copilot/README.md`
- **Invoice recipes**: Read `.claude/skills/email-copilot/SKILL-RECIPES.md`
- **User rules**: `.claude/skills/email-copilot/rules.md`
- **Action log**: `.claude/skills/email-copilot/action-log.md`