Commands

TUI

Running mp with no arguments launches a full-screen terminal interface built on ratatui: a mailbox sidebar, the message list, and the headers and body of the selected message. The sidebar hides below 40 columns and the right panes below 80.

Like the CLI and the Mac app, the TUI is a client of the local daemon, which syncs every account and pushes new mail to it.

Selectors

Every command that names a message takes a selector, never a file path: mp://<account>/<mailbox>/<key>. For received mail the key is the Message-ID without its angle brackets; for a draft the mailbox is the reserved name drafts and the key is the id: field in the draft's frontmatter, so renaming the file does not change its selector.

The leading segments can be left off: the account falls back to -A/--account or the first account in your config, and the mailbox to --mailbox or the command's own scope. mp send 9f2c1ab30d5e4471 and mp send mp://work/drafts/9f2c1ab30d5e4471 are the same command. A key that matches messages in two mailboxes is reported with both full selectors rather than resolved by guesswork; --mailbox picks one. Every command that creates or lists something prints the fully qualified form, which pastes straight into the next command, and mp path <selector> is the one way back to a filesystem path.

On a terminal, mp new, mp edit, mp reply, mp forward, mp mark-approved and mp mark-draft print ✓ <selector>, mp archive prints the selector it moved the message to under ✓ archived, and mp save prints ✓ <path> per file. When stdout is a pipe or a file, each prints only the bare selector or path, one per line, so sel=$(mp new note) && mp path "$sel" works as written.

Draft Commands

IMAP Commands

Local Store Commands

Offline reads over what mp sync already brought down. They open no connection: they answer from the per-account store, so they work on a plane and cost nothing. The one exception is mp show of a message the store does not hold, below.

mp list-messages prints one line per message with its full selector, which pastes straight into mp show, mp reply or mp archive. With no --mailbox it lists every mailbox of the account, grouped, and the limit applies per mailbox so a busy inbox cannot hide the others. The order is the one the TUI's flat list shows (tc switches an account to it).

mp show takes the same selector grammar as every other message command, so the bare Message-ID is enough when it is unambiguous, and an mp://<account>/... selector reads that account's store rather than the default one. A selector that names its mailbox but no message the store holds, such as a sent message mp search found on the server that no sync stored, is fetched from the server into the store first, with a note on stderr; mp save and mp open do the same. A body the store no longer holds (evicted, or never ingested) prints as a note under the headers instead of failing. --json is the parseable form: one object with the envelope, the attachment list and the body as a JSON string.

mp dump-mailbox --json is a different tool with a similar shape: it is the parity oracle, emits newline-delimited envelopes without bodies for every account, and its record shape is pinned. Read mail with these two; diff stores with that one.

Maintenance Commands

Mailypoppins used to keep received mail as one Markdown file per message under ~/.local/share/mailypoppins/accounts/<account>/. It now keeps it in a SQLite store beside a content-addressed blob store, and those old inbox/, archive/ and sent/ directories are dead weight. mp cutover is the one-time tidy-up: it lists each dead directory with its size and prints the rm line that removes it.

It never deletes anything itself, and there is no migration on startup: it runs only when you run it. Its one write is the id: frontmatter field, which is how a draft written by the old build becomes addressable by selector; running it again writes nothing, and --dry-run writes nothing at all. Drafts are the only local-only data in the product, so they are the only thing the old directories hold that the server cannot give back, and they were never in those directories to begin with.

Config Commands

Daemon Commands

Every command that touches your mail asks a background daemon over a Unix socket, and starts one if none is running. These manage it directly; mp daemon * never starts a daemon it was only asked to report on.

Shell Completions

mp completions <bash|zsh|fish|elvish|powershell> prints a completion script for every command and flag on stdout. It reads no config and needs no daemon.

# zsh: save it on your fpath, then restart the shell
mp completions zsh > "${fpath[1]}/_mp"

# bash: load it in ~/.bashrc
eval "$(mp completions bash)"

Contacts Commands

Fetch Options

Sync Options

Sync is additive by default: it fetches new emails only, deduplicated by Message-ID. A two-pass strategy first downloads headers (~50 bytes per message) to identify new emails, then fetches full RFC822 bodies only for messages not already stored locally.

Deletes are handled by the same pass. The download is capped by --limit, the enumeration never is, so a message the server no longer lists is pruned from the local store however far it sits below the newest ones, and a mailbox emptied elsewhere does not linger.

Invite Options (mp send --invite)

mp send --invite sends an iMIP calendar invitation (METHOD:REQUEST) over SMTP that renders as an actionable Accept / Tentative / Decline event in Outlook, Gmail, and Apple Mail. Attendees come from --to/--cc and the subject is reused as the event summary. Times accept local wall-clock (2026-07-20T14:00, "2026-07-20 14:00") or RFC3339 with an offset (2026-07-20T14:00:00+02:00, ...Z); a timed event needs either --end or --duration. The ORGANIZER is the sending account's primary address (Exchange drops mismatches). Graph accounts are not yet supported for invites.

A bare date as --start sends an all-day event, which calendars show in the all-day row. Without --end it covers that one day. --end names the last day, inclusive, so --start 2026-12-24 --end 2027-01-08 covers 24 December through 8 January; the invitation carries the day after as its exclusive DTEND, as RFC 5545 requires.

To change an invitation already sent, send it again with --uid set to its UID (shown in the preview and in its invite.ics) and a higher --sequence (the first send is 0, so the first update is 1). Calendar clients replace the event only when the UID matches and the sequence is higher than the one they hold; without --uid the invitation is a new event.

mp send --invite --to me@example.com --subject "Kita closed" --start 2026-12-24
mp send --invite --to me@example.com --subject "Christmas holidays" --start 2026-12-24 --end 2027-01-08
mp send --invite --to me@example.com --subject "Kita closed" --start 2026-12-24 \
  --uid 3f2a...@example.com --sequence 1

RSVP to Invitations (mp invite)

mp invite accept|tentative|decline <selector> replies to a received calendar invitation. It reads the invite email's sidecar invite.ics (the source of truth for UID/SEQUENCE), builds a METHOD:REPLY with your account as the single ATTENDEE carrying the chosen PARTSTAT (ACCEPTED/TENTATIVE/DECLINED), and emails it to the ORGANIZER with an Outlook-convention subject (Accepted: <summary>, etc.). On a successful send the local event.rsvp is updated. v1 answers the whole series only (no per-occurrence responses) and adds no note text.

In the TUI, invites show a calendar badge in the list and an event summary card at the top of the preview pane; press tv to open an Accept / Tentative / Decline overlay. The RSVP is emailed to the organizer only — it is not synced to your Exchange server calendar (no Graph in v1). Graph accounts are not yet supported for RSVP.

Organizer RSVP Tracking (mp calendar rebuild)

When someone accepts or declines an invitation you sent with mp send --invite, their reply arrives as a METHOD:REPLY email during normal sync. mailypoppins matches it by event UID to your sent invitation and shows that attendee's status on the invite, so you can see who responded. The statuses are computed from the stored invitation and reply messages every time they are shown, so the agenda and the preview card are always current with what has arrived.

mp calendar rebuild [-A NAME] reports what those replies resolve across every stored invitation (defaults to all accounts). It writes nothing: there is no cached copy of the statuses to rebuild, so it is idempotent by construction, and two machines syncing the same account see identical state with no direct machine-to-machine sync. Replies for a SEQUENCE older than the invitation's are ignored, and the most recent reply per attendee wins. Nothing is written back to the server — without Graph, your server-side Exchange calendar is never touched.

Global Options

Search Query Syntax

The mp search command, its --local mode and the TUI server search overlay (f) all speak one grammar. Fields AND together, (a OR b) groups an alternation, and quoted values are supported (e.g., from:"John Doe"). Sylvain's example from:boss@corp.com (invoice OR receipt) has:attachment runs on every backend. Without an in: prefix or --mailbox, all the account's mailboxes are searched. A malformed query is an error with a caret pointing at the problem, never a silent search for less.

Flags (same query, for scripting)

Every field has a matching flag; a flag invocation builds the identical query as its positional twin, so mp search --from boss@corp.com --has-attachment 'invoice OR receipt' equals mp search 'from:boss@corp.com (invoice OR receipt) has:attachment'.

has:attachment across backends

On Gmail and Microsoft Exchange has:attachment runs server-side. Plain IMAP (RFC 3501) has no attachment search key, so mp answers that part from the local store's synced mail and prints a warning that un-synced mail is not covered; run mp sync for full coverage. The result header on stdout repeats it, as in Fetched Emails (3 results, local store only: has:attachment) or No results found (local store only: has:attachment), so a script that drops stderr still sees it, and --json carries "coverage": "local" with the term in local_terms ("coverage": "server" when the server answered every term). The TUI's server search overlay and the desktop app's search bar put the same caveat after their count, as in 2 results (local store only: has:attachment).

Local full-text search (--local)

mp search --local <query> answers from the local store's FTS5 index instead of the server: offline, ranked best match first, and covering every synced mailbox of the account at once. A subject hit outranks the same word buried in a quoted reply. The index is written in the same transaction as the message it describes, so it is never stale with respect to what mp sync has pulled, and it holds only what has been synced, which is what the server-side search is still for. Punctuation is searched as text, not as query syntax.

TUI Key Bindings

Generated from the single KEYMAP source of truth (clients/tui/src/app/keymap.rs) via mp dump-keys --json; see scripts/regen-website-keys.sh. These match the in-TUI help overlay (?) exactly.

The copy keys (y, and c in Contacts) write to the system clipboard. Over ssh the remote host usually has none, so the TUI sends the text to your terminal as an OSC 52 escape sequence instead. Ghostty, WezTerm, kitty, iTerm2 and tmux with set-clipboard on put it on your local clipboard. The status line then shows the copied text, so you can still select it by hand in a terminal that ignores OSC 52.

GLOBAL

MESSAGE (list, headers, body)

SIDEBAR

EMAIL LIST

SERVER SEARCH

CONTACTS

CALENDAR

HEADERS

BODY

ACTIVITY LOG