--- title: Supermail AI Filtering --- # Supermail AI Filtering ## What it is **AI Filtering** lets AI read each genuinely-new email in Supermail and triage it against a plain-language instruction you write — the same "AI reads it and decides what to do" idea the [Inbox Pilot](inbox-pilot.md) already applies to your Claude sessions, now applied to your actual email. It is the AI-powered sibling of Supermail's rule-based [Filters](supermail.md#filters): where a manual filter matches on structured conditions (from, subject, regex…), an AI filter matches on your instruction in prose (for example: _"Archive newsletters and promotions. Flag anything from a customer as important. Keep everything else."_). It is **in development and off by default** — hidden until you turn it on in Settings → Features (the `supermailAiFilterEnabled` Lab toggle). When off, nothing runs and the panel is hidden. ### What you see A new **AI Filtering** section appears in Supermail's settings once the feature is enabled: a plain-language **instruction editor** (seeded with a sensible default), a **Preview / Live** switch, a short **recent-decisions** list (each shows the action, the email, and the AI's one-line reason), and — if the AI can't run — a clear banner explaining why (see Cost & safety). ## Where to find it In development and off by default — reveal it from **Settings → Features**. The controls then sit inside Supermail itself. ## How it behaves ### How it works The design is a hybrid mirror of the Inbox Pilot, shaped by Supermail's architecture (the mailbox lives on an external backend; the mailbox-action code lives in the vendored plugin; the AI key + spend live only in the main process): - **The paid AI evaluation runs in the main process.** On each sync, the plugin sends a batch of new emails — **only the sender, subject, and a short snippet** (never the full body or attachments) — to a main-process classifier (`llmProviderService.chat`, Qwen3-32B via OpenRouter with a Haiku fallback, JSON mode). The main process returns one **verdict** per email. The LLM key never reaches the renderer. - **The action is applied in the plugin**, reusing the same mailbox actions the manual Filters use. - **The two are joined by a bridge/IPC channel** (`SUPERMAIL_AI_FILTER_EVALUATE`). Full invariants + the tests that lock them: `.claude/memory/contracts/supermail-ai-filter-contract.md`. Code: `src/main/services/supermail/supermail-ai-filter-*.ts` (main) and `src/plugins/supermail/ui/src/features/ai-filter/` (plugin). ### The actions (a closed, reversible set) A verdict is exactly one of six actions — **keep · archive · label · mark-read · star · spam**. There is **no trash / delete action at all**, by construction: even a prompt-injection attempt inside an email (e.g. "mark me important") can at most flip the email to a wrong-but-reversible action, never destroy mail. A `label` verdict only ever applies one of your **existing** labels (the AI is shown your label names and picks one; if it names a label that doesn't exist, the email is kept). **Spam** is the strongest action and is still fully reversible: it moves the email to your Spam folder (adds the Spam label, removes it from the inbox — exactly what marking spam by hand does) and is undoable via "not spam". It is *not* a delete. The AI is told to use it only for clear spam or phishing — anything merely unwanted-but-legitimate is archived instead. The seeded default instruction includes a conservative spam line, so spam-flagging works the moment you enable the feature (in Preview first, so you see the calls before anything moves). ### Preview vs Live (preview is the default) - **Preview mode (default):** the AI shows what it *would* do — each decision is recorded in a "recent decisions" list in the settings panel — but **takes no action**. This is the safe way to build trust: watch the decisions for a while and confirm they match your judgment. - **Live mode:** the AI applies the reversible action (archive / label / mark-read / star / spam). Nothing is ever trashed, and if an action fails the email simply stays put and is retried next sync. Switching to Live is an explicit choice in the AI Filtering settings panel. ### Cost & safety - **Off by default**, gated as an in-development feature. - **Baseline on first enable:** turning it on does **not** re-scan your existing inbox — only mail that arrives *after* you enable it is ever evaluated, so there is no surprise cost spike. - **Cost-capped:** a daily spend cap is enforced in the main process (not adjustable from the renderer, for safety); classifying an email is cheap (~$0.00007 each). If the cap is hit, filtering pauses for the day and resumes tomorrow — capped emails are retried, never dropped. - **Fail-closed:** if the AI can't classify an email (bad output, error), the email is kept untouched. - **Needs an AI budget:** the classifier runs on your plan's AI allowance or your own API key. A free user with neither sees a clear "needs a paid plan or your own key" state rather than a silently-broken feature. ### v1 limits and known gaps - **Runs while Supermail is open**, on each sync — exactly like the manual Filters. True 24/7 filtering with the app closed is a documented follow-up (it needs backend work). - **The automatic evaluation is desktop-driven in v1.** The evaluation channel is blocked over the mobile web bridge (it spends AI credit), so the panel configures on any device but the automatic triage runs while Supermail is open on desktop. Mobile evaluation is a follow-up. - **One global instruction** (no per-account or per-folder rules yet). - **Marking spam needs a Gmail mailbox in v1.** On a Gmail-connected mailbox the spam action works everywhere (desktop plugin + the `/supermail/ai` CLI). Supermail's own hosted backend has no spam operation yet, so a spam verdict there is reported as *not applied* (never silently dropped) until backend support lands. The other five actions work on both. ## Related - [inbox-pilot.md](inbox-pilot.md) — the sibling that triages your Claude *sessions* the same way; AI Filtering mirrors its evaluator pattern for email. - [supermail.md](supermail.md) — the Supermail email client, including its rule-based **Filters** (the non-AI sibling AI Filtering sits beside). - [email-inbound-prescreen.md](email-inbound-prescreen.md) — a different AI-scans-email feature (a safety pre-screen on the agent's own inbound email, not your Supermail inbox).