Description

IMAP email scanning and triage with AI classification via a local Ollama LLM. Scans unread emails, categorizes them as urgent, needs-response, informational,...

README (SKILL.md)

Email Triage

Name: email-triage
Author: briancolinger

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.

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

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.

Usage Guidance

This skill appears to implement an IMAP triage tool, but there are important inconsistencies and privacy risks to consider before installing: - Do not supply your real email password unless you trust the source. The script requires IMAP credentials (IMAP_HOST, IMAP_USER, IMAP_PASS) even though the registry metadata does not declare them — verify this omission with the publisher. - Prefer an app-specific password (not your main account password) and store it in a secrets manager rather than exporting it in an interactive shell. - By default the classifier will send email excerpts to the configured OLLAMA_URL. Keep OLLAMA_URL at the default localhost address (127.0.0.1) unless you explicitly trust and control the remote endpoint; pointing it to an external URL can leak message content. Note the default scheme is http — that would transmit data in plaintext if pointed off-host. - Fix the invocation path mismatch (SKILL.md examples reference scripts/email/email-triage.py but the shipped file is scripts/email-triage.py); test the script in a controlled environment first. - Review the full script (especially any remaining truncated portions) to confirm there are no unexpected network calls or hidden endpoints before giving it credentials. If you want to proceed: run the script in a disposable/test account first, use an app-specific IMAP password, keep OLLAMA_URL set to localhost, and consider running the script on a machine you control rather than in a shared/cloud agent environment.

Capability Analysis

Type: OpenClaw Skill Name: email-triage Version: 1.0.1 The skill is suspicious due to its handling of sensitive IMAP credentials (IMAP_USER, IMAP_PASS) from environment variables and the potential for data exfiltration of email metadata (sender, subject, preview) via the configurable OLLAMA_URL. While the default OLLAMA_URL points to a local endpoint (http://127.0.0.1:11434), allowing it to be set to an arbitrary external URL via an environment variable (as seen in `SKILL.md` and `scripts/email-triage.py`) introduces a significant vulnerability. A malicious actor could configure this URL to an external server, leading to unauthorized disclosure of email content to an untrusted third party. This is a critical configuration risk, even if not explicitly malicious in the default setup.

Capability Assessment

⚠ Purpose & Capability

The skill's stated purpose (IMAP email triage) matches the included code (imaplib scanning, classification, local state file). However the registry metadata claims no required environment variables or primary credential, while both SKILL.md and the script require IMAP credentials (IMAP_HOST, IMAP_USER, IMAP_PASS). This mismatch is a meaningful inconsistency: the skill will need access to sensitive email credentials but that is not declared in the registry metadata.

⚠ Instruction Scope

SKILL.md directs running the bundled Python script to scan unread emails and store a local JSON state — which is what the code implements. Problems: (1) the command examples reference scripts/email/email-triage.py but the actual file is scripts/email-triage.py (path mismatch that will break invocation), (2) the classifier sends email excerpts to OLLAMA_URL (default http://127.0.0.1:11434) — if a user sets OLLAMA_URL to a remote host the script will transmit email content off-host, and the default uses plain HTTP so content could be exposed if pointed to a non-local endpoint, (3) instructions do not explicitly warn about data sent to arbitrary OLLAMA_URL values. The instructions otherwise stay within the stated purpose (reading IMAP, classifying, saving state).

✓ Install Mechanism

There is no install spec (instruction + code only) and the only declared binary dependency is python3, which is proportionate. Nothing in the manifest downloads or executes remote installers. This is the lowest-risk install mechanism, but runtime network behavior remains relevant.

⚠ Credentials

The script requires sensitive environment variables (IMAP_HOST, IMAP_USER, IMAP_PASS) and may also use OLLAMA_URL/OLLAMA_MODEL. Those variables are necessary for IMAP access and optional LLM use, so their presence is plausible — but the registry metadata failing to declare them is a red flag. Also, because the classifier sends email content to the configured OLLAMA_URL, allowing that URL to point to a remote/untrusted endpoint would permit exfiltration of email contents. IMAP_PASSWORD is particularly sensitive and should be treated as a secret; the skill doesn't declare or document secure secret handling (e.g., not advising secret manager use).

ℹ Persistence & Privilege

The skill writes a local JSON state file (default ./data/email-triage.json) to persist classifications; that is reasonable for the purpose. It does not request always:true and does not modify other skills. Be aware that autonomous invocation (normal default) combined with stored IMAP credentials means the agent could scan mail on a schedule — expected behavior, but it raises privacy considerations.

Version History

v1.0.1

Fix security scan flags: declare runtime dependencies, document env vars and write paths

v1.0.0

Initial release of email-triage. - Scans IMAP inbox for unread messages and classifies them as urgent, needs-response, informational, or spam. - Uses a local Ollama LLM for AI-powered categorization, with a rule-based heuristic fallback if Ollama is unavailable. - Surfaces important emails (urgent and needs-response) for agent review. - Stores classification state locally, deduplicates messages, tracks surfaced status, and prunes old records. - Offers command-line commands for scanning, reporting, marking surfaced emails, and displaying stats. - Configurable entirely via environment variables; works standalone or with Ollama for improved accuracy.

Metadata

Slug email-triage

Version 1.0.1

License —

All-time Installs 12

Active Installs 11

Total Versions 2

Frequently Asked Questions

What is email-triage?

IMAP email scanning and triage with AI classification via a local Ollama LLM. Scans unread emails, categorizes them as urgent, needs-response, informational,... It is an AI Agent Skill for Claude Code / OpenClaw, with 2136 downloads so far.

How do I install email-triage?

Run "/install email-triage" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is email-triage free?

Yes, email-triage is completely free (open-source). You can download, install and use it at no cost.

Which platforms does email-triage support?

email-triage is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created email-triage?

It is built and maintained by Brian Colinger (@briancolinger); the current version is v1.0.1.

More Skills

email-triage