Omniscio

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 a pending_sends row and fires the real sendMessage when the window elapses; Undo cancels it server-side (DELETE /messages/pending/:id).
  • Search supports negated operators (-from:, -label:, -in:, -has:, -is:) end-to-end (backend query-parser → NOT clauses; 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 s is normally Star, one-key Star relocates to D, and Q is added as a left-hand alias for Label (its l still works) while the mode is on. Preference persists to supermail:left-handed-nav (features/settings/left-handed-nav-setting.ts). It is applied as an effective keymap: getEffectiveKeymap(leftHandedNav) in features/shortcuts/keymap.ts drops the bare-s Star binding and appends LEFT_HANDED_NAV_BINDINGS (w/s/d + q→label); both keymap consumers (app-shortcuts.tsx, use-inbox-actions.ts) read it so s is never bound to two actions at once. The Shortcuts drawer swaps its nav/Star/Label rows via getShortcutCatalog; 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 (e Done, # Trash, s Star, u Unread, h Snooze, 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 to supermail:hover-act (features/settings/hover-act-setting.ts); off restores hover = prefetch-only. Implemented as focusRowOnHover in features/shortcuts/hover-focus.ts, wired into all three list surfaces (inbox, label folders, snoozed) — every shortcut already targets focusManager.getFocusedId(), so moving focus is all it takes. Each page's focusManager subscriber skips its focus→reading- pane mirror for hover-driven focus via isHoverSuppressingPaneMirror(), and the existing pointerMovedTo guard 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 (buildRfc822 returns 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 + threadId and 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 same openWithSeed seed 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 by filter-manager-store), not only from Settings. Bare T is 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 in manual mode) — 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.dev web 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-filters skill 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 backend src/protected/filters/.

The overview, the other parts, and everything else worth reading next all sit on Supermail.

Last verified 2026-10-06