Name: email-triage
Availability: InStock
Author: briancolinger

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.

Configuration

All configuration is via environment variables:

Variable	Required	Default	Description
`IMAP_HOST`	✅	—	IMAP server hostname
`IMAP_PORT`	—	`993`	IMAP port (SSL)
`IMAP_USER`	✅	—	IMAP username / email address
`IMAP_PASS`	✅	—	IMAP password or app-specific password
`EMAIL_TRIAGE_STATE`	—	`./data/email-triage.json`	Path to the JSON state file
`OLLAMA_URL`	—	`http://127.0.0.1:11434`	Ollama API endpoint
`OLLAMA_MODEL`	—	`qwen2.5:7b`	Ollama model for classification

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

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

Icon	Category	Description
🔴	`urgent`	Outages, security alerts, legal, payment failures, time-critical
🟡	`needs-response`	Business inquiries, questions, action items requiring a reply
🔵	`informational`	Receipts, confirmations, newsletters, automated notifications
⚫	`spam`	Marketing, promotions, unsolicited junk

email-triage

AI Skill Market Insights

Be Part of the 2,140+ Developer Community

Email Triage

Prerequisites

Categories

Configuration

Directories Written

Commands

Scan with verbose output (shows each classification)

Dry run — scan and classify but don't save state

Show unsurfaced important emails (urgent + needs-response)

Same as report but JSON output (for programmatic use)

Mark reported emails as surfaced (so they don't appear again)

Show triage statistics

How It Works

Integration Tips

Quick Start

Manual Installation

TEAR & SHARE

Tags

writing-plans

executing-plans

plan-ceo-review

Office Automation

Todo Manager

Channels

Learn

Compare

Company