email-copilot

name	email-copilot
description	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.
hints	["email","inbox","mail"]

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):

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

# 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

## YYYY-MM-DD

### Trashed
- [account] [e-mail] - "Subject" (reason: auto-trash match / user confirmed)

### Moved
- [account] [e-mail] - "Subject" → Label/Name

### Kept
- [account] [e-mail] - "Subject" (user decision: reason)

### Patterns Identified
- [e-mail] 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