The mailcoded manual

This is the handbook for people who read their own mail with mailcoded, from a terminal. It covers installing it, adding an account, the full-screen client, every command-line verb, sending, and what to do when something goes wrong.

It is deliberately not the design documentation. If you want to know why the daemon speaks JSON-RPC or how the sync planner works, start at docs/ARCHITECTURE.md. If you are giving an AI agent access to your mail, docs/agents.md is the document for you; chapter 11 here only points at it.

Everything in this manual was checked against mailcoded 0.1.0, protocol 1, on 2026-09-06, by running the commands. Where the manual and mailcoded help <verb> disagree, the program is right and the manual has a bug — please report it.

The short version

scripts/install.sh      # build, and put the four commands on PATH
mailcoded setup         # add an account; nothing is saved until a real login succeeds
mailcoded tui           # read it. Press ? for the keys.

Contents

1. Installing — build from source, where the binaries go, checking it works
2. Your first account — setup, provider quirks, app passwords, Microsoft sign-in, scripted setup
3. Where your mail lives — the data directory, what is in it, secrets, backups, editors
4. The terminal client — mailcoded tui: the screen, keys, mouse, reading, triage, compose
5. Reading and searching from the command line — search, read, thread, attachments, folders
6. Triage — Tags and Flags, tag, move, archive, and why there is no delete
7. Sending — drafts, the two-phase send, the outbox, and who the send gate applies to
8. Accounts — account list, test, reauth, add, forget
9. Sync and the daemon — sync, live updates, one daemon per store, running the daemon yourself
10. Importing mail and raw SQL — import-eml, query --sql, reading the audit trail
11. Agents — the two-minute version, and where the real document is
12. The safety model, in plain terms — what mailcoded will never do, and why you may see �
13. Troubleshooting — the messages you might see, what they mean, what to do
14. Reference — environment variables, exit codes, every key, every verb, every file

Conventions

• mailcoded is the command-line tool. mailcoded-tui, mailcoded-daemon and mailcoded-mcp are the other three binaries the installer puts beside it; you rarely run them directly.
• <id> is a local message id — the number in the first column of search output. It is stable within one store and means nothing outside it.
• The vocabulary is deliberate and the manual sticks to it: an account has folders (never “mailboxes”); a message carries server Flags (unread, flagged, replied, draft) and local Tags (never “labels”).
• --json output is a contract, versioned by schema_version. The human-readable output is not, and may change between releases.