margin-mail/docs/features.md

Features

The specification for version one. Each feature says what it does, how it is invoked, the rules it follows, where its state lives, and what the provider (Gmail for now) sees. "Local" means the portable state database described in architecture.md, which roams through the backup store and never depends on the provider. "Provider" means a change made to the mailbox itself. The reasoning behind the choices is in design.md; the screens are in ui.md; every key is in keyboard.md.

1. Places

A place is a view. Numbers reach the seven daily ones, 0 reaches Everything, and the palette reaches all of them.

Key	Place	What it holds
1	Inbox	Threads from senders routed to Inbox, plus any reply to a thread you are in
2	Feed	Threads from senders routed to Feed, rendered open
3	Paper Trail	Threads from senders routed to Paper Trail
4	Reply later	The Reply later pile
5	Set aside	The Set aside pile
6	Screener	First messages from senders with no decision yet
7	Snoozed	Threads waiting to return, with their return time
0	Everything	Every thread on the device, including archived, spam and screened out, in date order
palette	Sent, Drafts, Starred	The usual folders
palette	Screened out, Spam, Trash	Under Other: the places you go looking in rather than read
palette	All files, Clips, Contacts	The libraries
palette	Labels	The provider's labels or folders, one place each

Every place except Feed, Screener and Focus & Reply is a list column beside the reading pane. Feed and Screener take the whole stage because their content is inline. A place remembers its scroll position and selection while the app is open.

Every place is a view over what is on the device, and what is on the device is a window of the mailbox: the last 30 days by default, or 90, 180, 365 days or everything, set per account. Threads you have done something to are kept whatever their age. Only Everything says any of this out loud, in one quiet line at the foot of the list, "Showing the last month. Older mail is on Gmail.", with the setting one click away. The mechanism is in architecture.md and the setting is in settings.md.

2. Routing and the Screener

Destinations

Every sender has exactly one destination: Inbox, Feed, Paper Trail, or Screened out. The rule is keyed on the sender's address, or on the domain when the user chose "everyone at this domain". Address rules beat domain rules. Consumer domains (gmail.com, outlook.com, yahoo.com, icloud.com, proton.me, hey.com and a maintained list) cannot carry a domain rule.

Two overrides apply before the sender rule:

• A message whose In-Reply-To or References points at a thread the account is already in goes where that thread is, or to the Inbox if the thread was screened. A reply is never held.
• A message from someone the account already knows is screened in on first run and routed by the suggestion rules, never held. Who counts as known is settled under First run below.

The Screener

A message from a sender with no rule is held: it is not shown in any box, and the Inbox shows a pill "Screen N new senders". The Screener place lists one card per sender: avatar, name, address, subject, snippet, and a one-line reason with the suggested destination. Keys:

• y accepts the suggestion and sets the rule for the address.
• v opens the destination picker: Inbox, Feed, Paper Trail, and a toggle for "everyone at this domain".
• n screens the sender out. Nothing is sent. Their mail is routed to Screened out from then on.
• Enter expands the card to show the whole message, with a Reply button that screens the sender into the Inbox and opens a reply.
• Clear all screens out every sender currently waiting, after a confirmation.

Screened out mail sits in the Screened out place for as long as the storage window keeps it and falls off the device with everything else of that age. There is no second retention rule to remember, and a wider window means a longer memory. Reversing a decision is done from the sender's contact card, and re-screening someone in brings back whatever they sent that is still here.

Suggestions

The suggestion is a deterministic function of the first message, and the reason shown is the rule that fired. In order:

1. Written by a person: no List-Id, no List-Unsubscribe, no Precedence: bulk or list, no Auto-Submitted, a From local part that is not noreply, no-reply, donotreply, notifications, mailer, bounce or similar. Suggest Inbox.
2. Carries List-Unsubscribe, List-Id or Precedence: bulk, or Gmail put it in CATEGORY_PROMOTIONS. Suggest Feed.
3. Sent by a service for a person, or transactional: a no-reply local part, Gmail's CATEGORY_UPDATES, or a subject matching receipt, order, confirmation, invoice, shipped, payment, verify, code, ticket, itinerary, reservation. Suggest Paper Trail.
4. Anything else: Inbox.

Rule 3 wins over rule 2 when both match, because a receipt with an unsubscribe footer is still a receipt. The rules are a table in the source and the reason strings are the table's rows, so a wrong suggestion is a one-line fix.

First run

When an account is added, everyone it already knows is screened in with a rule set by the same suggestion function, silently. A month of mail is not by itself a good answer to who a person knows, so the seed is drawn from three cheap sources at once: every sender and every recipient inside the storage window, the People API's connections and otherContacts lists, and the Sent mail inside the window. Anyone in any of the three is screened in. All three are already fetched or already on the way, so this costs a pair of extra calls and no waiting.

The pass runs at the end of the first sync rather than when the first-run panel is dismissed, so the Inbox fills as the mail arrives instead of sitting empty for as long as somebody takes to read a panel. It runs once per account and is guarded, which is the whole of what makes the Screener a gate: if it ran again on a later sync it would screen in every new sender the moment they wrote. The guard cuts the other way too: asked before the crawl has finished, as it is the moment an account is added from Settings, the seed answers "not yet" rather than marking itself done over a mirror with nothing in it, and the sync's own idle asks again. A seed on record as having screened in nobody is run once more when the mirror is ready, which repairs an account that was marked that way before the rule existed without anybody removing it and connecting it again.

The user can move any sender from the contact card, and the move applies to that sender's existing threads immediately. Only senders whose first message arrives after the account was added are held in the Screener.

Alongside this, a first-run panel offers "Start fresh": mark everything older than a chosen age (default one week) as seen, so New for you holds only what is recent. This is the only bulk write to the provider the app ever proposes, it is optional, and it is reversible for seven days from the palette.

State: sender rules are local, keyed on address or domain. Provider: nothing. A held or screened-out message keeps whatever labels Gmail gave it.

3. The Inbox

Two groups, fixed order, newest first within each: New for you (threads with at least one message the account has not seen) and Previously seen (everything else routed to Inbox, including sent threads). A third group, Back, appears above New for you when a snoozed thread has returned, and holds it until it is opened.

• Opening a thread marks it seen. u toggles seen on the selected thread. Mark all as seen is a link on the New for you heading and a palette command.
• A new message in a Previously seen thread moves the thread to New for you.
• e archives: the thread leaves the Inbox and lives in Everything. A new message in an archived thread brings it back to New for you. Archive is a provider change (Gmail: remove INBOX).
• There are no counts on the groups or on the place. The one count anywhere is the dock badge, which is the size of New for you across every account, and it is on by default and turns off in Notifications. It is not the mailbox's unread count: a thread held in the Screener, routed to the Feed or the Paper Trail, piled, snoozed or ignored is unread and is not waiting for you. Zero takes the badge off rather than showing a nought. macOS and Linux carry it; Windows would need a drawn overlay icon and does not have one yet.
• A note on a thread shows as a single line under its row.

Seen state is the provider's read state (Gmail: UNREAD), so it is not app state. Everything else about the Inbox is a view over the mirror plus the sender rules.

4. The Feed

The Feed renders every thread routed to it as an open card: brand avatar, sender and address, time, the subject as a title, and the message body. A card longer than one screen truncates with a fade and "Read more"; Enter on the focused card expands it in place, Enter again collapses. A hairline reading "You left off here" marks the newest card that was on screen at the end of the last visit.

• No read state, no counts, no New for you. Time is the only order.
• Card actions: Read more, Save clip, Unsubscribe, Move (to Inbox or Paper Trail, for this sender), Set aside, Reply later, Archive, Trash. All with keys.
• j and k move between cards and scroll the focused card into view.
• Remote images obey the same rules as the reading pane. Trackers are stripped and the top of the Feed says how many today.
• Feed threads older than a configurable age (default never; HEY defaults to 90 days) can be trashed automatically per sender from the contact card.

5. The Paper Trail

A flat list, newest first, of threads routed to it. No read state. A sender with more than one thread in the last seven days is bundled into one row showing the count and the latest subject; Enter expands the bundle in place, and bundling can be turned off per sender from the contact card and off entirely in settings. The reading pane works as in the Inbox. Verbs are the same as the Inbox minus the seen toggle, plus Move to Inbox.

6. The piles

Reply later

l on a thread, or on a selection, moves it out of its list into the Reply later pile. The pile is a stack of cards at the foot of the list column showing the top thread's subject and sender; 4 or a click opens the Reply later place, which lists the pile with the reading pane. l again returns the thread to where it came from. Sending a reply on a Reply later thread clears it from the pile with an undo toast.

Set aside

s does the same into the Set aside pile at the bottom right. 5 opens the place. s again returns the thread. Set aside is for reference, so a thread can sit there indefinitely; nothing nags.

Focus & Reply

Shift+F, the palette, or the button in the Reply later place. A page listing every Reply later thread, each with its latest message on the left and a reply box on the right. Tab moves to the next item, Cmd+Enter sends and collapses the item to a "Sent to" line, Esc leaves the page. Items you skip stay in the pile.

State: pile membership and order are local, keyed on the thread key. Provider: nothing. A piled thread keeps its Gmail labels; it simply does not render in the Inbox list.

7. Snooze and reminders

b opens the snooze picker on a thread or selection: Later today (in three hours), Tomorrow (8:00), This weekend (Saturday 9:00), Next week (Monday 8:00), Pick a date and time, and If no reply by (a date; default tomorrow). The thread leaves its list and appears in the Snoozed place with its return time.

When a device opens the app, comes to the foreground, or wakes from sleep, it evaluates every snooze whose time has passed and returns those threads to the Back group at the top of the Inbox (or the top of the Feed or Paper Trail if that is where they live). If no reply by returns the thread only if nobody but the account has written to it since; a reply cancels the reminder and the reply lands as normal. A returned thread stays in Back until opened.

Nothing runs in the background and nothing fires at an exact time. The Snoozed place shows the return time so the user can see what is pending, and a thread that returns late says "Due yesterday" rather than pretending.

In compose and inline reply, Remind me if no reply is a toggle in the footer with the same date picker. It applies to the sent thread after the send completes.

State: snooze entries are local (thread key, return time, kind). Provider: nothing.

8. Reading

The reading pane shows the selected thread. Subject in the text face, participants and message count beneath, then messages separated by hairlines. Older messages collapse to a one-line preview; the latest is open. n and p move between messages, o expands or collapses the focused message, Shift+O expands all. Quoted text is collapsed behind a pill.

• Message bodies render in a sandboxed webview with scripts, forms and external styles removed. Remote images are blocked by default; a banner says how many trackers were stripped and names the vendor; Show images loads them for this message, and the contact card can allow them for a sender always. Attachments are chips; pressing one opens the file with whatever owns its type.
• Attachments are fetched when the thread is opened, not during sync, and cached.
• A calendar invite (text/calendar with METHOD:REQUEST) renders as a card: date, title, time, location, organiser, and Accept (y), Maybe (m), Decline (n), plus Open in Margin Calendar. RSVP goes through the Calendar API on the invited calendar; when the event is not there yet it is imported first. The Calendar permission is not asked for when the account is added, so the first RSVP says it needs it and runs the consent page again; until then the card renders read-only.
• Links show their real destination on hover and open with known tracking parameters removed.
• Read together: select several threads with x and press Enter; the pane shows them one after another with a heading each.
• The pane can be hidden (Cmd+\); the list then takes the width and Enter opens a thread in place, HEY style, with Esc returning to the list.

9. Writing

Reply and new mail

r replies to the sender, a replies to all, f forwards; each opens a box under the last message with the recipients shown as chips and reply-all as a one-key switch. c opens the compose card floating over the list, bottom right; the expand button or Cmd+Shift+P makes it the whole window. Drafts save locally as you type and to the provider every few seconds, so a draft roams the way Gmail drafts always have.

The editor is TipTap, as in margin: paragraphs, bold, italic, links, lists, quotes, code. No colours, no fonts. Plain-text mail is sent as plain text. The signature comes from the provider's settings for the sending address and is editable in settings.

Sending

Cmd+Enter sends. Every send is held for ten seconds (five, twenty or thirty in settings) with a toast "Sent to X · Undo"; z or the toast cancels and reopens the draft. Cmd+Shift+Enter sends immediately. Sends that fail or happen offline wait in the outbox and retry, and the thread shows a "Waiting to send" line until they go. Threading headers (In-Reply-To, References, the provider's thread id, a matching subject) are always set so replies land in the thread on both ends.

Remind me if no reply

A toggle in the send footer with a date. See section 7.

Instant intro

Cmd+Shift+I in a reply to an introduction moves the introducer to Bcc and inserts a thank-you line from a template that can be edited in settings. Pressing it again reverts.

Attachments

Drag and drop, paste, or Cmd+Shift+A. The composer refuses anything that would push the encoded message over the provider's limit (Gmail: 35 MB total) and says so before you try to send.

Not in this version

Snippets, send later, and any AI assistance. The compose footer leaves room for them.

10. The things HEY owns, kept beside the mail

Notes

y on a thread adds a private note. In the pane it is a block after the message that was latest when it was written, dated; in the list it is one line under the row. Text only in this version. Local, keyed on the thread key.

Rename

Click the subject or run Rename from the palette. The pane shows the new name with "renamed · was …" beside it, the list shows the new name, and replies still carry the real subject so threading holds on both ends. Local.

Merge

Select two or more threads and press g. They become one thread in every list and in the pane, named after the longest one or a name you type. A banner on the merged thread says where it came from and offers Unmerge. Replies and new messages in any underlying thread appear in the merged one. Local: a mapping from the underlying thread keys to a merged key.

Clips

Select text in any message and the Save clip button appears; Cmd+Shift+C also works. The Clips place lists every clip with its sender, thread and date, and each links back. Local.

All files

The All files place lists every attachment in the mirror as a card with name, type, size, sender and thread, newest first, with filters by type (images, PDFs, documents, spreadsheets, presentations, calendar invites, archives, other) and by sender. Signature junk (images under 10 KB referenced inline) is excluded. Opening a card opens the thread with the attachment focused. Built from the local index; nothing is fetched until you open one.

Ignore

m on a thread. New messages still arrive and append, and the thread rises with them because the Inbox is in time order, but it never reads as new, never counts on the badge and never notifies. A banner on the thread says "You are ignoring this thread" with Stop ignoring. Local.

Notifications

Off by default everywhere. Shift+N on a thread turns them on for that thread; the contact card turns them on for a person; Settings turns them on for a place, and has one switch over all of it for the machine, which is what "nothing on this laptop" means without touching a single thread. The sync pass that brings a message in is what posts the notification, and only for mail that arrived after the app came up, so a first sync, a rebuild or a week away says nothing about the backlog; one message is three lines, the app's name, the sender and the subject, and several in one pass are one notification counting them and naming the senders. On macOS the system asks once whether the app may notify at all, the first time anything here is turned on or the test button is pressed, and a refusal is undone in System Settings rather than here. Clicking one brings the app to the front and opens the thread in the list it shows in; a click on the grouped one opens the account's Inbox, and a click on the sample from Settings only brings the app to the front. The dock badge is a setting in the same section rather than a notification, it counts New for you, and it is the one thing here that is on. Local.

11. Contacts and the contact card

i on a thread, or clicking a name or avatar anywhere, opens the contact card as a popover: avatar, name, address, then Delivers to (the destination, changeable), Notify, Screened (in or out, with the date), Note, Recent threads, Files, and Unsubscribe when the sender's mail carries List-Unsubscribe. The Contacts place lists every sender with a rule and lets you search them.

Autocomplete in compose draws first on the addresses in the mirror (everyone you have written to or received from, ranked by recency and frequency) and second on the provider's contacts (Google: People API otherContacts and connections).

State: notes, delivery, notify are local. Provider: nothing.

12. Unsubscribe, block, spam, trash

• Unsubscribe (Cmd+U, the Feed card, or the contact card): with an RFC 8058 one-click header the app POSTs and confirms; with a mailto: header it sends the message; otherwise it opens the link. Either way it offers "and trash everything from them" and "and screen them out".
• Screen out from the contact card is the block: future mail goes to Screened out. Nothing is sent.
• ! marks spam and # trashes, both provider changes, both with an undo toast.

Screened out, Spam and Trash

Three places under Other in the palette, below the daily ones and below the labels, with no number keys of their own. Where a place sits is the honest statement of how often you should be in it, and these are the ones you go looking in rather than the ones you read.

None of them is a filter of ours. Gmail's spam filter runs on Gmail's side before the app sees a message, and the mirror takes what the mailbox holds: every list call sets includeSpamTrash, so a junked message is already on the device with its body indexed whether or not anything shows it. Screened out is the one we own, and it is a routing destination rather than a folder, so its rules are in section 2.

Getting mail back out is the point of all three, and the verb that puts it back is the verb that put it there, the way the piles already work. # in Trash puts a thread back, ! in Spam takes the spam mark off. Gmail restores a message's labels when the TRASH label comes off, so a thread put back lands where it was rather than in the Inbox. A thread taken out of Spam is routed like any other: to its sender's box if that sender has a rule, and to the Screener if they do not, which is the decision you still owe them.

There are three ways back, in the order you will want them. A wrong keystroke is the toast that is already up, "Trashed · Undo" and z. A rescue a week later is the place and the verb. After thirty days Gmail empties its own trash, the message leaves the mirror with it, and nothing local changes that.

There is no Empty button. Permanently deleting through the Gmail API needs the https://mail.google.com/ scope, which is total access to the mailbox, and asking every account for that so a button can destroy things thirty days earlier than Gmail will anyway is a bad trade. Each place states the rule instead, in one line at the foot of the list: "Gmail empties this after 30 days." Screened out carries no such line, because it falls off with the storage window like everything else of its age and there is no second retention rule to learn.

13. Selection and bulk actions

x selects the focused row, Shift+J and Shift+K extend, Cmd+A selects all from here, Esc clears. While a selection exists the piles are replaced by an action bar with the same verbs and keys: Reply later, Set aside, Snooze, Mark seen, Archive, Move, Merge, Ignore, Trash, and Enter for Read together. Every bulk action is one undo.

14. Search

/ focuses search. Results replace the list column and the reading pane works as usual. Search is local over what is on the device: subject, participants, snippet and body text, with operators from:, to:, subject:, has:attachment, filename:, in: (any place), before: and after:, label:.

Because the device holds a window, a local result set is a partial answer and says so. Every list of results ends with "Search older mail on Gmail", which runs the provider's search, appends the hits and hydrates them as they arrive. Those rows behave like any other row, and the next eviction pass takes them away again unless they picked up a pile, a note or some other decision in the meantime. A query whose before: or after: falls outside the window skips the local index entirely and goes to the provider, because a local answer to that question would be wrong rather than merely short. Results open in place and Esc returns to the previous place.

Search reaches Spam, Trash and Screened out, and names the place on the row when it does. The message you most need to find is the one something else decided you should not see, and a search that skipped those three would be one you had to already know the answer to use. in: narrows to a single place when that is what you meant.

15. Accounts

Add as many Gmail accounts as you like. Each has its own places, sender rules, piles, Screener, storage window and granted permissions, so a work account can keep a year while a personal one keeps a month. The account chip in the title bar switches (Ctrl+1 to Ctrl+9) and offers All accounts (Ctrl+0), which merges every account's version of the current place into one list with a coloured edge on each row. Compose picks the account from the thread you are replying to, or the account you are looking at, and the From field switches it. Sent mail goes through the sending account; an alias verified on the provider can be chosen in From.

16. Labels

The provider's labels or folders are places, listed under Labels in the palette. Shift+L applies or removes one on the selected threads, v moves (applies a label and archives). They are the provider's, they roam with the mailbox, and they are not how Margin organises anything.

17. Settings and export

Settings is a place, not a panel. Cmd+,, the palette, the account chip and the app menu all lead to the same full-stage screen, with a rail of sections down the left and one section at a time on the right. Twelve sections cover the accounts and their permissions, appearance, the storage window, privacy, the Screener, the piles and snooze, writing, notifications, the keymap, backup and the recovery phrase, every export the app offers, and the version. Each is specified in settings.md, including which of them live on the device and which roam.

18. Help

The app is unlike the mail clients people arrive from, and none of the differences are discoverable by poking at the interface, so there is a tour, a question mark in the corner, and a guide behind it. Each is specified in help.md.

The tour is nine slides in a sheet, over the Inbox, run once for every account that is added and skipped with one key. It follows the first-run panel above and names the Screener, the three boxes, the two piles, snooze, the keyboard, the palette, the things kept beside the mail, what is off by default, and undo.

The corner button opens the tour again, the guide, and the keyboard shortcuts. It is not drawn while the compose card is open, while an overlay is up, in the guide itself, or on a phone.

The guide is a panel over the whole window: a search field, a rail of sections, and one article at a time. How to do each thing the app does, and last, the questions people actually ask. Every article leads with its answer and shows it in a drawn figure, a screenshot or a table of keys, and a search nothing answers offers to file the question against the repository. Closing it puts back the place, the open thread and the scroll. Its pictures come from the dev fixture through just guide-shots and are committed, because they ship in the bundle.

State: which accounts have had their first run, and therefore their tour, is a device fact in localStorage beside the first-run panel's own flag. Provider: nothing.

19. Not in version one

Send later. Snippets. Any AI. Shared threads, team comments, read statuses. Workflows, collections, cover art. A calendar sidebar. Unified search across accounts (search is per account until the unified view is proven). IMAP and JMAP providers (the trait is there; the implementations come after Gmail is solid).