Email Triage

Scan your IMAP inbox, classify emails into priority categories, and surface the ones that need attention. Uses a local LLM (Ollama) for intelligent classification with a rule-based heuristic fallback when Ollama is unavailable.

Prerequisites

• Python 3.10+
• IMAP-accessible email account (Gmail, Fastmail, self-hosted, etc.)
• Ollama (optional) — for AI-powered classification. Without it, the script uses keyword-based heuristics that still work well for common patterns.

Categories

Configuration

All configuration is via environment variables:

Directories Written

• EMAIL_TRIAGE_STATE (default: ./data/email-triage.json) — Persistent state file tracking classified emails and surfacing status

Commands

# Scan inbox and classify new unread emails
python3 scripts/email/email-triage.py scan

# Scan with verbose output (shows each classification)
python3 scripts/email/email-triage.py scan --verbose

# Dry run — scan and classify but don't save state
python3 scripts/email/email-triage.py scan --dry-run

# Show unsurfaced important emails (urgent + needs-response)
python3 scripts/email/email-triage.py report

# Same as report but JSON output (for programmatic use)
python3 scripts/email/email-triage.py report --json

# Mark reported emails as surfaced (so they don't appear again)
python3 scripts/email/email-triage.py mark-surfaced

# Show triage statistics
python3 scripts/email/email-triage.py stats

How It Works

1. Connects to IMAP over SSL and fetches unread messages (up to 20 per scan).
2. Deduplicates by Message-ID (or a hash of subject + sender as fallback) so emails are never classified twice.
3. Classifies each email using Ollama if available, otherwise falls back to keyword heuristics.
4. Stores state in a local JSON file — tracks category, reason, and whether the email has been surfaced.
5. report surfaces only unsurfaced urgent and needs-response emails, sorted by priority.
6. mark-surfaced flags reported emails so they won't appear in future reports.
7. Auto-prunes state to the most recent 200 entries to prevent unbounded growth.

Integration Tips

• Heartbeat / cron: Run scan periodically, then report --json to check for items needing attention.
• Agent workflow: scan → report --json → act on results → mark-surfaced.
• Without Ollama: The heuristic classifier handles common patterns (automated notifications, marketing, urgent keywords) well. Ollama adds nuance for ambiguous emails.
• App passwords: If your provider uses 2FA, generate an app-specific password for IMAP access.