imail — IMAP Email Screener

Automated email screening and organization for IMAP accounts. Fetches emails by date range, applies rule-based and optional AI classification, and moves messages to appropriate folders.

Quick Start

tsc                    # compile (or tsc -watch in VS Code)
node index.js          # run with defaults
node index.js -ai cli  # run with AI analysis via Claude CLI

Command-Line Options

| Flag | Description | Default | |------|-------------|---------| | -d <days> | Number of days to process | 10 | | -b <begin> | Start from this many days ago | 1 | | -box <folder> | Folder to use instead of INBOX | INBOX | | -g | Poll Gmail accounts only | all | | -i | Poll IMAP (non-Gmail) accounts only | all | | -ai <mode> | AI analysis mode: api, cli, none | cli | | -noai | Shortcut for -ai none | | | -v | Verbose output | off | | -ignoreCerts | Ignore invalid/expired SSL certificates | on | | -certs | Require valid SSL certificates | |

Architecture

index.ts              Entry point, arg parsing, main loop
imailsettings.ts      Shared settings type (ImailSettings)
screener/
  cleaner.ts          Core processing — fetch, screen, move messages
  screener.ts         Static rule engine
rules/
  rules.ts            Pattern-matching rules (to/from/subject)
analyze/
  analyzer.ts         AI analysis via Anthropic API (api mode)
  clianalyzer.ts      AI analysis via Claude CLI (cli mode, uses Max plan)
  icswriter.ts        Generate .ics calendar files from detected events
html/
  htmlreport.ts       HTML report generation

AI Analysis

Two modes available via -ai <mode>:

• cli (default) — Spawns claude -p per message. Uses your Claude Max plan (no API charges). Requires claude CLI installed.
• api — Direct Anthropic API calls. Model configured in ../config/mailsettings.json under ai.model. Costs per-token.
• none — No AI analysis, rules only.

AI results are cached in ai/analyzed.json keyed by message ID. Delete the file to re-analyze.

VS Code Debugger Note

When running from the VS Code debugger (F5), the NODE_OPTIONS env var contains --inspect flags. The CLI analyzer strips these so the child claude process doesn't inherit them and fail.

Rules

Edit rules/rules.ts to add/modify email screening rules. Rules match on to/from/cc addresses, subject lines, and sender names. Destination "*" means trash.

Configuration

• Server credentials: ../uinfo module
• AI settings: ../config/mailsettings.json (ai section)
• AI guidance: ai/ai.md (custom classification hints)
• Debug output: y:\temp\imapper
• CLI analysis logs: logs/ directory