Interfaces
One engine, many surfaces: the desktop app, the airpost CLI, the MCP server, the web client and service plugins, and when to use each.
Airpost isn’t only a desktop app. All of your mail lives in one process, airpost-engine, and several programs act as windows onto it. Whichever one you use, you are working on the same accounts, the same local database, the same drafts, rules, templates, snoozes and settings.
The engine is the only process that talks to your mail provider or holds your passwords and tokens. The socket is reachable only by your own user. Clients don’t keep their own copy of your mail; they ask the engine and receive deltas when something changes. The web client is the one exception to direct socket access: it reaches the engine only through the gateway. The engine and Security model go deeper.
The surfaces
| Surface | Program | Best for | Access |
|---|---|---|---|
| Desktop | The Airpost app | Everyday reading and writing, calendar and contacts | Everything |
| CLI | airpost | Scripts, terminals, quick checks, managing background services | Everything your user can do |
| MCP | airpost-mcp | AI assistants that should work under limits | Read; read and draft; or read, draft and send. Per-account and per-folder limits, audit log |
| Web | airpost-gateway + web client | Mail in a browser, from your computer or a server | Browsers you pair with a one-time code |
| Service plugins | Your own program | Background automation that keeps running with the desktop closed | Whatever the plugin is written to do |
Desktop
The desktop app bundles its own engine, so you don’t install anything else to use it. The engine can keep running after the app quits; the background services in Preferences > General control that, so scheduled sends, snoozes, rules and agents keep working. The same pane puts the airpost command on your PATH.
CLI
airpost covers status, accounts, threads, search, show, drafts, archive, trash, move, labels, snooze, reminders, rules, templates, signatures, unsubscribe, contacts, calendar, tasks, logs, settings and a live watch. Every command accepts --json. It also installs and manages Airpost’s background services as launchd or systemd user units (airpost engine install, airpost gateway install, airpost mcp-http install, airpost service install). See CLI overview.
You can run the CLI without the desktop: airpost engine install runs the engine on its own and airpost account add connects accounts to it.
MCP
airpost-mcp is an MCP server. Over stdio it plugs into Claude Desktop, Claude Code and Codex (airpost-mcp install --client claude-code); over streamable HTTP it uses a bearer token. You pick an access level, which accounts and folders the agent can see, and every call goes into an audit log. Use MCP when you want an agent to have less than full access. See Agents and Access levels.
There is a second way to give an agent your mail: airpost skill install adds a skill that teaches Claude Code and Codex to use the airpost CLI. That route has full access, the same as you at your terminal, and none of the MCP limits. See The agent skill.
Web
airpost-gateway serves the web client and relays it to an engine. On your own computer, airpost gateway install and airpost gateway pair are enough. On a server, deploy/server/ runs the engine headless with the gateway, the web client and a TLS proxy from one compose file. See Self-hosting.
Service plugins
A service plugin is a separate program that connects to the engine socket and is run by launchd (macOS) or systemd --user (Linux) after the engine, also while the desktop is closed. You install one from Preferences > Plugins (“Install service…”) or with airpost service install <name>; both show the binary, its SHA-256 and the units before writing them. See Plugins and Service plugins.
Which one should I use?
One task, five ways
The task: find unread mail from Alice with attachments, and snooze it until tomorrow morning.
- Type
from:alice has:attachment is:unreadin the search bar. - Select the threads.
- Click Snooze in the toolbar and pick Tomorrow.
The threads move to Snoozed and come back to the inbox at the chosen time.
Whichever way you do it, the engine records the snooze and runs the timer. The threads come back at 9:00 the next day whether the desktop is open or not, as long as the engine is running.
Things that are shared
- Settings the engine keeps: undo send delay, the default sending account, signatures, templates and mail rules.
airpost settingsreads and changes them, and the desktop shows the same values. - Undo: the engine keeps an in-memory log of the last 100 changes from the last 24 hours. Each client undoes its own changes by default (
airpost undo --anytakes back anyone’s). The log is cleared when the engine restarts. - Live updates: every client receives deltas as they happen.
airpost watchprints them, which is a quick way to see what another client is doing.
Things that aren’t shared
Layout, theme, shortcuts and other window preferences belong to the desktop app. MCP access levels and hidden folders apply only to airpost-mcp. Gateway pairings apply only to the web client.