neomd

A keyboard-first TUI email: write in Neovim, render as Markdown, screen senders first, organize emails once.

_Neomd is my way of implementing an email TUI based on my experience with Neomutt, focusing on Neovim (input) and reading/writing in Markdown and navigating with Vim Motions with the GTD workflow and HEY-Screener._

The philosophy behind Neomd: What's unique?

The key here is speed in which you can navigate, read, and process your email. Everything is just a shortcut away, and instantly (ms not seconds). It's similar to the foundations that Superhuman was built on: it runs on Gmail and makes it fast with vim commands.

With the HEY-Screener, you get only emails in your inbox that you _screened in_, no spam or sales pitch before you added them. Or don't like them, just screen them out, and they get automatically moved to the "ScreenedOut" folder.

With the GTD approach, using folders such as next (inbox), waiting, someday, scheduled, or archive, you can move them with one shortcut. This allows you quickly to move emails you need to wait for, or deal with later, in the right category. Processing your email only once.

Also, we intentionally don't add more folders to the archive or file emails too, only archive (and work if you use business/personal - but that's not even needed). The goal is to let emails fade out, avoid the "busy work," and file them. We use search when we need it, or copy important information into Obsidian or our daily work. That's why we only have limited folders (and also why we currently can't add additional ones; see FAQ.

But we have two additional Feed and Papertrail, two dedicated folders from HEY where you can read newsletters (just hit F) on them automatically in their separate tab, or move all your receipts into the Papertrail. Once you mark them as feed or papertrail, they will moved there automatically going forward. So you decide whether to read emails or news by jumping to different tabs.

Email Processing Workflow

Here's how neomd combines HEY-Screener + GTD + Feed/Papertrail to process your email:

flowchart TD
    Start([New Email Arrives]) --> AutoScreen{Auto-Screener<br/>Known Sender?}
AutoScreen -->|screened_in.txt| Inbox["📥 Inbox (Next)"]
    AutoScreen -->|screened_out.txt| ScreenedOut[🚫 ScreenedOut]
    AutoScreen -->|feed.txt| Feed[📰 Feed]
    AutoScreen -->|papertrail.txt| PaperTrail[🧾 PaperTrail]
    AutoScreen -->|Unknown| ToScreen[❓ ToScreen]
ToScreen -->|Press I| ClassifyIn[Add to screened_in.txt]
    ToScreen -->|Press O| ClassifyOut[Add to screened_out.txt]
    ToScreen -->|Press F| ClassifyFeed[Add to feed.txt]
    ToScreen -->|Press P| ClassifyPaper[Add to papertrail.txt]
ClassifyIn --> Inbox
    ClassifyOut --> ScreenedOut
    ClassifyFeed --> Feed
    ClassifyPaper --> PaperTrail
Inbox --> Process{Process Email<br/>GTD Decision}
Process -->|< 2 min?<br/>Do it now| Action[Reply/Handle<br/>Immediately]
    Process -->|Waiting for others<br/>Press Mw| Waiting[⏳ Waiting]
    Process -->|Not now, later<br/>Press Mm| Someday[📅 Someday]
    Process -->|Time-specific<br/>Press Mc| Scheduled[🗓️ Scheduled]
    Process -->|Delete<br/>Press x| Trash[🗑️ Trash]
    Process -->|Reference only<br/>Press Mp or P| PaperTrail
    Process -->|Newsletter<br/>Press F or Mf| Feed
Action --> Done{Done?}
    Waiting --> Review[Review Later]
    Someday --> Review
    Scheduled --> Review
    Feed --> ReadLater[Read in<br/>Feed Tab]
    PaperTrail --> SearchLater[Search when<br/>needed]
Done -->|Yes| Archive[📦 Archive]
    Done -->|Not actionable| Archive
    Review --> Archive
    ReadLater --> Archive
classDef folderStyle fill:#54546d,stroke:#7fb4ca,stroke-width:2px,color:#dcd7ba
    class ToScreen,Inbox,ScreenedOut,Feed,PaperTrail,Archive,Waiting,Someday,Scheduled,Trash folderStyle

_all colored boxes represent neomd folders_

Key principles:

• Screener first: Unknown senders never clutter your Inbox, but get automatically wait in ToScreen for classification more
• One-time decision: Once you classify a sender (I/O/F/P), all future emails from them are automatically routed more
• GTD processing: Emails in Inbox are processed once. Inbox acting as want/need to do _Next_, otherwise move to Waiting, Someday, or Scheduled
• Minimal filing: Only Archive when done; no complex folder hierarchies. Use search to find old emails
• Separate contexts: Feed for newsletters (read when you want), PaperTrail for receipts (search when needed)
• See full features list below.

Screenshots

Overview: List-View

Feed view with all Newsletters - also workflow with differnt tabs and unread counter only for certain tabs (not all): !neomd _Features seen: Reading newsletter directly in your email client (feed) - see spy pixel, if you have replied (dot) and thread mode if replied_

Reading Panel

Reading an email with Markdown 💙:

!neomd

Sent emails

This is the markdown sent:

# [neomd: to: [email protected]]
[neomd: subject: this is an email from neomd!]
This email is from Neomd. Great I can add links such as this with plain Markdown.
E.g. bold or _italic_.
Does headers work too?
this is a text before a h3.
H3 header
how does that look in an email?
Best regards

_Compose emails in your editor, read them rendered with glamour, and manage your inbox with a HEY-style screener — all from the terminal._

Which looks like this:

!neomd

Or in Gmail: !neomd

Video

YouTube rundown of most features: _(shorter but limited showcase part 1 video)_

Features

What Makes It Different

These features are the one that makes neomd different to other email clients out there.

• Write in Markdown, send beautifully — compose in $EDITOR (defaults to nvim), send as multipart/alternative: raw Markdown as plain text + goldmark-rendered HTML so recipients get clickable links, bold, headers, inline code, and code blocks →
• HEY-style screener — unknown senders land in ToScreen; press I/O/F/P to approve, block, mark as Feed, or mark as PaperTrail; reuses your existing screened_in.txt lists from neomutt; also acts as a phishing defense — impersonation emails from senders you've already approved land in ToScreen instead of Inbox, making them immediately suspicious →
• Glamour reading — incoming emails rendered as styled Markdown in the terminal →
• Spy pixel blocking — tracking pixels from newsletter services (Mailchimp, SendGrid, HubSpot, etc.) are automatically detected, counted, and stripped in the terminal view; ° indicator in the inbox and tracker domains in the reader header; browser view (O) injects a CSP that blocks scripts and frames — remote images are intentionally allowed there since you're explicitly choosing to see the full email →
• GitHub/Obsidian-style callouts — compose emails with callout syntax > [!note], > [!tip], > [!warning] for styled alert boxes in HTML emails; rendered with colored left borders, subtle backgrounds, and emoji icons →
• Server-side email tags (IMAP keywords) — t on the cursor email or a marked set toggles tags stored as IMAP keywords on the message: they survive reinstalls, follow the mail across folders, and other keyword-aware clients see them; filter the list by tag with f, delete a tag everywhere with D; tags show as coloured chips before the subject (nerd-font pills and glyphs optional), with per-tag display names and colours in config; a local per-account registry (~/.config/neomd/tags/) backs everything up →
• Private notes on an email (HEY-style thread notes) — n opens a popup with your private comment on the cursor/open email ("have replied", "this is the book email"); e edits it in $EDITOR as Markdown. The first line shows muted after the subject (✎), the whole note in the reader header. Stored as a tiny message in a neomd/Notes IMAP folder keyed by Message-ID — the email itself is never touched, and the note syncs to every machine; a local copy lives in ~/.config/neomd/notes/ →
• Listmonk newsletter integration — compose an email to a virtual address (e.g. [email protected]) and neomd creates a scheduled campaign in Listmonk via API instead of sending via SMTP; configure multiple trigger addresses to target different subscriber lists; pre-send screen shows campaign details →

Inbox & Screener

Keep your inbox clean without effort.

• Auto-screen on load — screener runs automatically every time the Inbox loads (startup, R); keeps your inbox clean without pressing S (configurable, on by default) →
• Whole-domain screening — list entries beginning with @ (e.g. @ssp.sh) match every address at that domain; per-address entries always win over a domain rule so a single blocked address inside an otherwise-approved domain stays blocked; press Di / Do to append @ to your lists with a y/n confirm →
• Background sync — while neomd is open, inbox is fetched and screened every 5 minutes in the background; interval configurable, set to 0 to disable →
• Headless daemon mode — run neomd --headless on a server to continuously screen emails without the TUI; watches screener list files for changes via Syncthing; perfect for running on a NAS while using the TUI on laptop/Android →
• Out-of-office auto-replies (screened-in only) — the headless daemon answers incoming mail with a [ooo] vacation reply, but only for senders on your screened-in list — spam, sales pitches, and unscreened senders never learn you're away (something server-side autoresponders can't do); one reply per sender per OOO period, RFC 3834 loop protection, markdown body rendered exactly like a hand-written neomd email, auto-expires on the until date →
• Desktop notifications for VIP senders — opt-in [notifications] block fires notify-send only for senders/domains you list in notify.txt; independent of screener categories; first run silently records a baseline so you don't get flooded →
• Folder tabs — Inbox, ToScreen, Feed, PaperTrail, Archive, Waiting, Someday, Scheduled, Sent, Trash, ScreenedOut →

Composing & Sending

• Pre-send review — after closing the editor, review To/Subject/body before sending; attach files, save to Drafts, or re-open the editor — no accidental sends →
• AI handoff (i in pre-send) — [ai].command (default claude) wires any LLM CLI (claude, codex, aichat, …) to the pre-send i key; neomd writes the draft to a temp markdown, spawns the command, and re-reads on exit when you quit the tool — header and body edits round-trip back. No in-app AI dependency →
• Attachments — attach files from the pre-send screen via yazi (a); images appear inline in the email body, other files as attachments; also attach from within Neovim via a; the reader lists all attachments and 1–9 downloads and opens them →
• Emoji reactions — press ctrl+e from inbox or reader to react with emoji (👍 ❤️ 😂 🎉 🙏 💯 👀 ✅); instant send with proper threading and quoted message history, no editor needed →
• Multi-select — m marks emails, then batch-delete, move, or screen them all at once →
• Undo — U reverses the last move or delete (x, A, M*) using the UIDPLUS destination UID →

Reading

• Threaded inbox — related emails grouped together with a vertical connector line (│/╰), Twitter-style; threads detected via In-Reply-To/Message-ID headers with a subject+participant fallback; newest reply on top, root at bottom; · reply indicator shows which emails you've answered →
• Merge threads (HEY-style) — collapse unrelated emails (mailer-daemon bounces, notification floods) into one titled ≡ row: mark with m, run :merge