Supermail (part 3)
The authoritative gap analysis + per-feature status lives in src/plugins/supermail/SUPERHUMAN_PARITY.md. As of 2026-06-23 the client is at near-parity; the non-AI gaps are closed end-to-end: Undo send is a true deferred send — the composer sends with undoWindowSeconds, the backend holds it on a pendingsends row and fires the real sendMessage when the window elapses; Undo cancels it server-side (DELETE /messages/pending/:id).
On this page
What it is
This is part 3 of the Supermail page. It carries the next stretch of the material on that page, moved here because a single page is capped at 40,000 characters.
Where to find it
Reach this part through Supermail — it lists every part and explains where the feature lives in the product. Everything below is reached from the same place.
How it behaves
Everything below is the behaviour, detail and edge cases that belong to this stretch of the Supermail page.
Feature status (Superhuman parity)
The authoritative gap analysis + per-feature status lives in
src/plugins/supermail/SUPERHUMAN_PARITY.md. As of 2026-06-23 the client is at
near-parity; the non-AI gaps are closed end-to-end:
- Undo send is a true deferred send — the composer sends with
undoWindowSeconds, the backend holds it on apending_sendsrow and fires the realsendMessagewhen the window elapses; Undo cancels it server-side (DELETE /messages/pending/:id). - Search supports negated operators (
-from:,-label:,-in:,-has:,-is:) end-to-end (backendquery-parser→NOTclauses; frontend renders exclusion chips). - Snippets can carry attachments (persisted in
snippets.attachments_json, applied to the draft on insert). - Follow-ups auto-resolve when a reply lands (the incremental sync calls
maybeResolveOnNewMessage). - First-run keyboard tour (
features/onboarding) drills the core shortcuts; replayable from Settings → General → Personalization. - Left-handed navigation (opt-in, OFF by default; Settings → Keyboard) — when
on, W = up and S = down in the inbox list, alongside the unchanged J/K +
arrow keys; because bare
sis normally Star, one-key Star relocates to D, and Q is added as a left-hand alias for Label (itslstill works) while the mode is on. Preference persists tosupermail:left-handed-nav(features/settings/left-handed-nav-setting.ts). It is applied as an effective keymap:getEffectiveKeymap(leftHandedNav)infeatures/shortcuts/keymap.tsdrops the bare-sStar binding and appendsLEFT_HANDED_NAV_BINDINGS(w/s/d + q→label); both keymap consumers (app-shortcuts.tsx,use-inbox-actions.ts) read it sosis never bound to two actions at once. The Shortcuts drawer swaps its nav/Star/Label rows viagetShortcutCatalog; the live help overlay reads the registry and already reflects it. - Hover to act (Settings → Keyboard; ON by default) — moving the mouse onto a
thread row moves the keyboard cursor to it, so the one-key shortcuts (
eDone,#Trash,sStar,uUnread,hSnooze, reply/forward, …) act on the hovered conversation with no click or explicit select first. It moves the cursor + row highlight ONLY — the reading pane still opens on click / Enter, never on hover. Preference persists tosupermail:hover-act(features/settings/hover-act-setting.ts); off restores hover = prefetch-only. Implemented asfocusRowOnHoverinfeatures/shortcuts/hover-focus.ts, wired into all three list surfaces (inbox, label folders, snoozed) — every shortcut already targetsfocusManager.getFocusedId(), so moving focus is all it takes. Each page's focusManager subscriber skips its focus→reading- pane mirror for hover-driven focus viaisHoverSuppressingPaneMirror(), and the existingpointerMovedToguard keeps a row that merely scrolled under a stationary pointer from hijacking the cursor. - Superhuman sidebar — pinned-vs-overlay nav with a hamburger drawer (auto-closes on mouse-leave) and a command-palette account selector. See "Sidebar: pinned vs overlay" above.
Still deferred (intentionally): AI (Ask/Summarize/Instant-Reply/Write), team collaboration, and live calendar — the only ⚙️ items left.
Sending from an IMAP (non-Gmail) mailbox
- A send goes out through the mailbox's own SMTP server, then a copy is filed in its Sent
folder with an IMAP
APPEND(backend/src/shared/mail/imap/send.ts). - The SMTP submission names its recipients explicitly — the sender plus every To, Cc and Bcc address — because a pre-built message is never read for recipients. Until 2026-09-26 that envelope was missing, and every IMAP send failed with "No recipients defined".
- Bcc stays private. SMTP hands the submitted bytes to every recipient unchanged, so that
copy is built WITHOUT its Bcc line (
buildRfc822returns both copies); the Sent-folder copy keeps it as the sender's own record. - Gmail mailboxes do not use this path: the Gmail API gets only
raw+threadIdand strips Bcc itself.
Filters (your own auto-acting rules)
Supermail has its own filter rules, separate from Gmail's filters, that automatically act on incoming mail. Manage them at Settings → Inbox → Filters (a master on/off toggle + a "Manage filters" launcher).
- Start one from a message (
T, right-click, or the funnel button) — press T on a focused inbox thread (or the open conversation), right-click any message row and pick "Filter messages like these", OR click the funnel button in the open email's top-right controls (all three share the sameopenWithSeedseed path), to open a new filter pre-seeded with that sender (From is exactly …— Gmail-style "filter messages like these"); you choose the action and save. The editor opens over the inbox (the manager is mounted app-level and driven byfilter-manager-store), not only from Settings. BareTis global; the seed carries no action so a real rule requires you to finish it. - Apply a new filter to your existing inbox on create. When you start a filter from an email, the
editor offers "Also apply to matching emails already in my inbox" — ON by default for that flow
(OFF for a blank "New filter" from Settings). Creating the filter then sweeps your whole current
inbox with that one new rule (not just future mail), refreshes the list, and reports the count; a
Trash-bearing sweep is confirmed first and the button shows a loading state. This is a manual,
one-shot apply (
runManualOnInboxForRule→ the runner inmanualmode) — it does NOT weaken the no-retroactive-sweep rule for the AUTO path (no-retroactive-sweep). - A rule is "conditions → actions." Match on sender, recipients (to/cc/bcc), subject, full body, sender domain, labels, date ranges, attachments (type/size), message state (unread/starred/muted/snoozed/has-link/calendar), and whether it's a mailing list (the message carries a List-Unsubscribe header) — each text condition can be contains, exact, regex, or fuzzy, combined with AND / OR / NOT.
- Actions: archive, add/remove label, move (= label + archive), mark read/unread, star, mute, snooze until a chosen delay, and mark as spam — all reversible, so they apply automatically. Forward to an address and auto-reply with a Quick Reply also apply automatically, but only behind a safety guard (next bullet). Trash is manual-only — never applied automatically (owner safety decision).
- Auto-forward and auto-reply are guarded. Because they send real email, they never fire on a mailing-list or no-reply message, on a thread you've already replied to, or to yourself; they send at most once per sender within a day and stop at a daily send cap. Like every auto action they never touch your existing inbox on enable, and a "Run on inbox now" that would send email is confirmed first. Note the whole engine runs client-side while the app is open, so auto-send is best-effort during that window, not a 24/7 server responder.
- When they run: automatically on new mail as it syncs in (while the app is open), plus a manual "Run on inbox now" for mail you already have. Enabling filters NEVER retroactively sweeps your existing inbox — only genuinely new mail is auto-acted, and each message is acted on once.
- Where it lives: your rules now live on the Supermail backend (like Split Inbox and
Flows), so they sync across your devices, the
mail.jls.devweb client, and AI agents. Only the matching runs client-side — that is what lets a rule use regex or fuzzy text (which a database can't evaluate). The master on/off toggle stays a per-device local switch. - Manage them from an AI agent / CLI. An agent hitting the Omniscio control server can list, create,
edit, delete, enable, and reorder your filter rules headlessly, and they sync straight to the app
— see the amc-control
supermail-filtersskill spoke. (Running rules over the inbox from the CLI is a planned fast-follow; for now use the in-app "Run on inbox now".) - Engineering invariants (idempotency, fail-closed deep matching, no-retroactive-sweep, regex safety,
reversible-or-guarded-send auto actions + the send-guard, backend storage + row-level security,
the CLI proxy):
.claude/memory/contracts/supermail-filters-contract.md. Code:src/plugins/supermail/ui/src/features/filters/+ the backendsrc/protected/filters/.
Related
The overview, the other parts, and everything else worth reading next all sit on Supermail.
Last verified 2026-10-06