Omniscio

Supermail — Inbox Emails & Row Density

The Mail and Sessions tab row that previously occupied ~160 px of sidebar space in the Mail view has been moved into a compact header above the email list. The previously-empty sidebar column is gone, giving the email list more horizontal room. Users who have the folder nav pinned ("Show sidebar" ON in Supermail's own Settings → General → Personalization) still see their folder list in that column — the change only eliminates the dead space when the nav is in overlay mode (the default).

On this page

What it is

How Supermail's mail list looks and how much room each email takes: the configurable header layout, the row spacing control, the reply indicator on threads you have answered, the cleaner conversation header, sender brightness and the attachment paperclip, and the setting that bounds how many emails sit in the inbox.

Where to find it

All of it is inside Supermail: the header above the email list, the rows themselves, and the reading pane.

How it behaves

What changed (layout polish — 2026-07-31)

The Mail | Sessions tab row that previously occupied ~160 px of sidebar space in the Mail view has been moved into a compact header above the email list. The previously-empty sidebar column is gone, giving the email list more horizontal room. Users who have the folder nav pinned ("Show sidebar" ON in Supermail's own Settings → General → Personalization) still see their folder list in that column — the change only eliminates the dead space when the nav is in overlay mode (the default).

This was the precursor to the configurable Header layout setting below (added 2026-08-04): the compact single-row header is now the default (unified), with the old two-row header still available as current.

Header layout (supermailHeaderLayout) — 2026-08-04

What it does — How it behaves

Chooses how the Mail | Sessions switch and the mail toolbar are arranged. Three layouts:

  • Unified (default) — ONE header row. The mail app's own toolbar carries a single Sessions button (chat-bubble icon + live count badge) at its right end, beside Help and View options — there is no separate Omniscio strip and no Mail tab (Mail is simply where you are). The button stays visible while emails are selected. The cleanest, lowest-chrome header.
  • Current — the legacy two-row header: the Omniscio Mail/Sessions strip sits ABOVE the mail app's own toolbar.
  • Left rail — the Mail/Sessions switch becomes a slim vertical icon rail on the LEFT of the mail app, freeing the whole top row.

Whichever layout is active, the control drives the SAME single tab source (supermailTab), so Mail/Sessions switching and the Sessions count badge behave identically. In the Sessions view (the mail app is hidden there) the switch always renders as the Omniscio strip atop the session list — horizontal for Current/Unified, vertical for Left rail.

How to change it — How it behaves

Settings → Email & Summaries → Header layout — a Current / Unified / Left rail control. Requires Supermail to be enabled.

  • Setting key: supermailHeaderLayout
  • Values: 'current' | 'unified' | 'rail'
  • Default: 'unified'
  • Takes effect immediately; no restart required.
  • How Unified works: it edits the mail app's own toolbar to host the Sessions button (a native component styled with the mail app's tokens, so the .supermail-scope typography never distorts it), driven by Omniscio through two bridge methods (getSupermailHeaderState + setSupermailTab) and a supermail-header push. Invariants + tests: .claude/memory/contracts/supermail-start-session-contract.md (header-layout-setting).

Row spacing / density (supermailDensity)

What it does — Controls how much vertical space sits between

Controls how much vertical space sits between emails in the Supermail list. It is built as a themeable baseline plus a per-level shift, so a custom theme controls the default spacing and the picker still tightens/loosens on top of it. Five levels, tightest → roomiest:

  • Tight — baseline − 6 px. On dense rows this removes the padding entirely (the floor is max(0, …)), for the most emails per screen.
  • Compact — baseline − 3 px (tighter), so you see more emails at once.
  • Comfortable (default) — the baseline spacing. With no custom theme this is each row variant's vendored default (dense rows 6 px, preview rows 12 px), so existing users see no change. A custom theme's supermailRowSpacing sets this baseline.
  • Spacious — baseline + 8 px (roomier), for an airier list.
  • Roomy — baseline + 16 px, the most breathing room per email.

Why five (2026-09-05). The original three spanned only −3 px…+8 px, so Compact vs Comfortable differed by 3 px per side — a change small enough to read as "nothing happened", which is what made the control look absent even to someone who found it. tight and roomy widen the ends; the original three keep their EXACT prior deltas, so no stored choice moved and no migration was needed.

The overrides live in Omniscio's globals.css (not in the vendored Supermail source). The picker sets --supermail-row-delta via a data-density attribute on the panel root; each row's padding is max(0, baseline + delta), scoped to the thread-list container so search results and pickers are never touched. Each row variant keeps its own fallback, so a theme never flattens the dense vs. preview layouts.

Make it themeable (custom CSS / themes)

A user-applied custom theme controls the row-spacing baseline — i.e. the default (Comfortable) spacing, which the other four levels then shift. A .theme.json sets the supermailRowSpacing key (a CSS length such as "10px"), which Omniscio emits as the --supermail-row-py CSS variable. This is the one themeable spacing token — see .claude/memory/contracts/custom-theme-tokens-contract.md. It takes effect immediately on the default view; picking any other level adjusts relative to the theme's baseline.

How to change it — Two places

Two places, both driving the ONE supermailDensity setting (they stay in lock-step — change either and the other reflects it):

  • In the Mail view (2026-08-10) — open the View options menu in the inbox header (the same sort · group · unread menu) and pick a Row spacing level: Tight / Compact / Comfortable / Spacious / Roomy. This is the in-context control, reachable in every header layout — including the default Unified, which shows no Omniscio chrome in Mail mode. The active level is checkmarked; the menu deliberately stays OPEN on select, so the list behind it re-spaces immediately and levels can be compared by eye without reopening the menu. This is the live view against your real inbox.

  • Settings → Email & Summaries → Row spacing — the same five levels, plus a live preview: three sample email rows that re-space as you pick. Settings sits nowhere near the mail list, so without the preview the control is blind. The preview is rendered by the SAME globals.css rule as the real thread list (.supermail-density-preview is joined into the dense-row selector and reads the same delta table), so it shows the actual resulting spacing, not an approximation — the two cannot drift. Requires Supermail to be enabled.

  • Setting key: supermailDensity

  • Values: 'tight' | 'compact' | 'comfortable' | 'spacious' | 'roomy' (the tuple SUPERMAIL_DENSITY_VALUES, ordered tightest → roomiest; both pickers MAP it rather than re-listing the levels, so a new level cannot go missing from a picker)

  • Default: 'comfortable'

  • Takes effect immediately; no restart required.

  • How the in-Mail control works: the vendored View-options menu reads + writes supermailDensity through the header-state bridge — getSupermailHeaderState seeds the current level LIVE (so the checkmark is never stale) and setSupermailDensity writes the pick back — the same channel that carries the Header layout, so the menu and the Settings control can never disagree. Invariants + tests: .claude/memory/contracts/supermail-start-session-contract.md (in-mail-row-density-control).

  • Migration: a legacy supermailCompactDensity: true install is migrated once to supermailDensity: 'compact' (the old boolean is then removed). Nothing migrates INTO tight or roomy — they are picker-only.

  • Adding a level: add it to SUPERMAIL_DENSITY_VALUES and give it a --supermail-row-delta rule in globals.css for BOTH .supermail-scope[data-density='…'] and .supermail-density-preview[data-density='…'], and add it to VALID_DENSITIES in the vendored header-state-store.ts (which cannot import the shared tuple). Miss the CSS and the level renders, persists and does nothing; miss the vendored copy and it is coerced back to Comfortable on the way into the mail app. Both failures are silent at runtime and are held by tests/unit/lint/1d/supermail-density-vendored-hooks.test.ts.

When you've replied (the reply indicator) — 2026-08-03

When the newest message in a thread is one you sent, the inbox row makes that obvious at a glance (Gmail / Superhuman style):

  • A small reply arrow (↩) marks the row.
  • The preview is prefixed "You:" and shows your most recent reply.
  • The row title stays the other person's name (not your own), so you still see who the thread is with — even on a thread with no subject line.

Details:

  • Keyed on your latest SENT message. The indicator shows only when the newest non-draft message in the thread is from your signed-in account. An unsent draft never triggers it. If the other person replies after you, their message becomes the newest and the row shows them again.
  • A note-to-self shows no indicator. An email with no other party — one you sent only to yourself — isn't a reply to anyone, so it shows neither the reply arrow nor "You:"; the row just reads "Me". The indicator needs a real counterparty (a send that also goes to someone else still counts).
  • "You:" is neutral, not colored — the reply arrow is the one accent mark.
  • No setting — it's automatic whenever Supermail can tell you sent the latest message.
  • Works across data sources. On the local-mirror (amc-gmail) path the other person's name is computed on read from the mirror — no re-sync, no migration; on the live path it's derived from the thread's own messages.

The row preview is always the newest message — 2026-10-25

  • What the row shows. The text after the subject is the newest non-draft message in the thread. An unsent draft never becomes the preview, and a thread that holds only drafts falls back to its own messages so the row is never blank.
  • A stale snapshot can never rewind it. The local mirror keeps a thread row as a cache of the thread, and more than one path fetches those rows (the incremental sync, and a paced backfill or reconciliation pass that fetches a thread and writes it minutes later). The row's date was already protected against an older write; its preview, subject and sender now are too, keyed on the thread's own Gmail historyId. A snapshot older than the row is a no-op, so a late write cannot put an older message back on top while the date stays fresh.
  • Rows already rewound heal on their own. Once a day the mirror re-reads the newest slice of the inbox (200 threads, the same paced, heavy-load-aware, kill-switchable pass the expired-watermark reset uses) without touching the sync watermark, so a row can never trail its thread by more than that window.
  • No setting — this is how the row always behaves. Owned by supermail-local-mirror-contract.md (a-stale-snapshot-never-rewinds-a-thread-row).

Cleaner conversation header — 2026-08-03

The header atop each open message (avatar · sender · "to …" · time) was realigned: the avatar is vertically centered against a two-line name / "to …" block, and the timestamp sits cleanly on the right with more breathing room. Visual polish only — no behavior or setting change.

Sender brightness & the attachment paperclip — 2026-08-07

Two small readability touches for the inbox list:

  • A read email's sender now matches its subject's brightness. Previously a read email's sender name was dimmed to the same faint grey as the preview text, so it could look washed-out next to its own subject. It now sits on the same brighter ink as the subject. Read vs. unread still reads clearly — an unread sender is heavier (bold), not a different colour. Subjects and unread senders are unchanged.
  • A paperclip (📎) marks a thread with a file attachment. The indicator already existed but never lit up on the local-mirror (amc-gmail) inbox, because that fast list carries no attachment data. It now shows on threads with a real file attached. Inline signature / logo images are ignored (matching Gmail), so a branded newsletter doesn't show a false paperclip. On the local-mirror path the flag fills in as your inbox finishes syncing, so a brand-new / cold inbox may take a moment before every paperclip appears.
  • No setting — both are automatic.

Emails in your inbox (supermailEmailsInInbox)

What it does — three choices

The setting is a three-way choice, so you can keep the heads-up for the mail that matters without letting the noise into the Omniscio inbox:

  • Off (default) — no email cards. Exactly as before.
  • All mail — every incoming Supermail email creates a dismissible card. This is what the old "on" did.
  • Important only — only mail Gmail marks important creates a card. Mail that would land in a split inbox's "Other" lane stays in Supermail and never reaches the Omniscio inbox.

Mail a filter archives on arrival never makes a card in any mode: the card is only for mail that is actually sitting in the inbox.

When a card is created it appears in the Omniscio unified inbox — the same inbox where sessions, approvals, SMS, and other sources appear — and carries an inline free-text reply box; submitting it sends your reply to the sender of that thread in the background.

Key behaviors:

  • One card per thread. The card uses a per-thread dedup key (supermail-mail-<threadId>), so a second email on the same thread updates the existing card rather than adding a new one.
  • Reply-to-sender only. The reply goes to the last sender of the thread — never reply-all, never to an earlier participant. The main process resolves the sender at send time; a missing sender address is a clear error before any send attempt.
  • Counts toward "Needs You". Email inbox items use sourceKind: 'agent' and therefore increment the Needs You badge on the project, the same as any other inbox item. This is a deliberate choice.
  • The inbox-card reply is desktop-only. The SUPERMAIL_SEND_REPLY IPC channel is in the web/mobile bridge's deny list — a paired phone cannot reply from this inbox card (the send path holds a credential that must never leave the main process). Replying from inside Supermail on the phone works — see "On your phone" in supermail.md.
  • No toast on arrival. The inbox badge increments silently; a toast fires only when a reply is sent successfully.
  • Cards do not depend on desktop notifications. Turning Supermail's desktop notifications off, switching on quiet hours, or setting the notification filter to important restricts TOASTS only. Cards follow this setting alone. (Before 2026-10-30 they followed the toast rules, so a user with desktop notifications off silently stopped getting cards.)
  • A big catch-up is capped. At most 25 cards are created per sync; anything beyond that becomes ONE card reading "N more new emails are waiting in Supermail", so a week away never walls the inbox and nothing disappears without a trace.
  • Dedup note. Archiving the card does not clear the dedup key — if a new email arrives on the same thread, the card is recreated (upsert). The user's previous reply text is not restored on the new card.

How to choose

Settings → Email & Summaries → Emails in inbox — Off / All mail / Important only. Requires Supermail to be enabled.

  • Setting key: supermailEmailsInInbox ('off' | 'all' | 'important')
  • Default: 'off'. A stored true from an older install reads as 'all' and false as 'off', so nobody's choice is lost on the upgrade.
  • Takes effect on the next incoming email; existing mail is not backfilled.

Archiving an email with its card (supermailArchiveSync)

One gesture, both places. Archiving an email card in the Omniscio inbox also archives that thread in Gmail, and archiving the thread in Gmail removes the card on the next sync.

Key behaviours:

  • On by default, with an off switch. Settings → Email & Summaries → "Archive emails with their cards". It can only ever act on an email card, so a person who has not turned on "Emails in inbox" sees no change at all.

  • One archive covers Gmail, Superhuman and Supermail. They all read the same Gmail account, so removing the Inbox label is all it takes.

  • Only your own gesture moves mail. Archiving the card archives the mail; replying from the card does not (the reply is the card's action, not a dismissal), and neither does an inbox rule, the Overseer, or an automatic clear.

  • The archive is durable. It goes through the same outbox as the Supermail panel's own archive, so a dropped connection or a restart does not lose it.

  • The reverse direction is a sync, not a push. Gmail is checked on the normal mail-sync cadence — about a minute while you are using the app, up to five minutes otherwise — so a thread archived in Gmail clears its card on the next pass, not instantly.

  • A reply brings the card back. Clearing a card because the thread left the inbox does not record a "dealt with" quiet period, and a new message on the same thread raises a fresh card.

  • Undo puts the mail back. Restoring an archived card returns its thread to the Gmail inbox.

  • One mailbox at a time. With more than one email account connected, the sync moves mail in the account you currently have open; a card from another account is dismissed without touching that mailbox.

  • Not covered: Supermail's separate "unread" rows in the inbox (supermailInboxEnabled) are a snooze surface, not these cards.

  • Backend-only accounts: with no Gmail connection there is no Inbox label to watch, so the clear-the-card direction applies only to the Gmail-connected path.

  • Setting key: supermailArchiveSync

  • Default: true (on)

The one place "Important only" behaves as "All mail"

The desktop reads mail two ways. In the default unified sign-in (supermailUseAmcGmail), the local mail mirror produces the cards and carries Gmail's labels, so the important filter applies. On the legacy Supermail sign-in the notifications arrive from the backend stream, whose message carries no label information — there, "Important only" creates the card anyway rather than risk losing mail you wanted to see. If you rely on the important filter, stay on the default unified sign-in.

How replies are sent

Submitting the inline reply form dispatches IPC.SUPERMAIL_SEND_REPLY to the main process, which fetches the thread to resolve the last sender's address, HTML-escapes your plain-text body, prepends "Re: " once (idempotent), and POSTs the reply to the Supermail backend. The JWT credential never reaches the renderer.

  • supermail.md — the full Supermail email client reference, including layout, filters, split inbox, and sidebar modes.
  • supermail-ai-filtering.md — AI-powered email triage (a separate feature).
  • Contract: .claude/memory/contracts/supermail-inbox-reply-contract.md — invariants, guards, and tests for the inbox-email / reply feature.

Last verified 2026-10-15