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

CODEBLOCK0

How It Works

1. 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.