How Airpost works
The parts of Airpost, how they connect, and where your mail and credentials live.
Airpost is a mail client that talks directly to your mail provider. There is no Airpost account and no Airpost server between you and Gmail, Microsoft or your IMAP server. One background program on your computer, the engine, does all the mail work, and everything you see (the desktop app, the airpost command, AI agents, the web client) is a separate program that asks the engine for what it needs.
This section explains that design for people who want to know what runs where: curious users, people wiring Airpost into scripts or agents, and anyone checking what it does with their data. If you want to work on the code, Architecture is the contributor-level version.
The big picture
The parts
| Part | Program | What it does |
|---|---|---|
| Engine | airpost-engine | Syncs every account, holds credentials, owns the database and search, runs tasks, send later, snooze, reminders and rules. The only program that touches mail. |
| Desktop app | Airpost | The window you use. Starts an engine if none is running and is a client of it. |
| CLI | airpost | Reads and acts on mail from a terminal, and installs the background services. See CLI. |
| MCP server | airpost-mcp | Gives AI agents access to your mail at the access level you choose. |
| Gateway | airpost-gateway | Puts the engine on the network for the web client, only for browsers you pair. See Self-hosting. |
No client embeds another, and no client reads the database directly. They all speak the same protocol over the same socket, so what the CLI or an agent sees is exactly what the app sees. The protocol types live in the airpost-ipc crate; Rust clients use airpost-client to find and talk to the engine.
Your provider is the source of truth
Mail lives on your provider’s server. The engine keeps a local copy in airpost.db so search is fast and you can read and triage offline, and it writes your changes back. If you delete the local database, nothing is lost: the engine downloads the mail again. Calendars and contacts work the same way through CalDAV, CardDAV and, for Gmail contacts, the Google People API.
See Sync for how the engine keeps the two in step.
One engine, every account
A single engine process (airpost-engine --mode serve) runs all your accounts. Each account gets its own set of threads and its own log file, and a failure in one account stops only that account. Clients attach to the engine over a Unix socket at <profile>/run/engine.sock, which only your user can open.
See The engine for the lifecycle, the socket and the protocol.
A change, from click to server
Every change you make goes through the engine as a task. The engine applies it to the local database first, so the app updates at once, then repeats it on the server.
If you’re offline, the local change stays and the remote phase waits. If the server refuses for good, mail changes such as read, star, move and labels are put back. The details are in Sync.
What runs locally
Everything that can run on your computer does: mail, search, calendar, contacts, snooze, send later, reminders, templates, signatures, rules, unsubscribe, undo, and AI with your own key or a local model. Scheduled work is done by the engine itself, so it doesn’t need a window open. See Local features.
Background mode
Closing the window doesn’t stop Airpost, so scheduled sends go out and agents keep working. On macOS Airpost always keeps running after you close the window; Show Airpost in the menu bar only shows or hides the icon. On Linux it keeps running while the tray icon is on (Keep Airpost running in the system tray). Quitting stops the app.
To keep the engine running even after you quit, turn on Keep Airpost running in the background in Preferences > General > Services on this computer. Airpost installs the engine as a launchd agent (macOS) or a systemd user service (Linux) that starts when you quit and when you log in. The same section can install the airpost command and turn on web access from this computer. The commands behind it are in Background services.
Your profile
Airpost keeps its settings, database, account list and logs in one profile folder: ~/Library/Application Support/Airpost on macOS, ~/.config/Airpost on Linux. Passwords and tokens are not in it in plain text; they’re in your OS keychain, or in an encrypted file on a server. See Profiles and data.
Trust boundaries
The engine is reachable only by processes running as you. Agents get the access level you set. Browsers get in only through the gateway after pairing. See Security model.
What needs an Airpost server
Read receipts, link tracking, thread sharing and settings sync between computers need an Airpost server. They aren’t available yet, and the app shows them as “Needs an Airpost server”. A server never holds your mail credentials in the same process that faces the internet: always-on features come from an engine running on hardware you control, behind the gateway. The Airpost server tab in Preferences describes what a server will add.
In this section
The engine
Sync
Local features
Profiles and data
Security model
Architecture
Credits
Airpost started as a fork of Mailspring by Foundry 376, LLC and contributors, with the sync engine rewritten in Rust. It isn’t affiliated with or endorsed by the Mailspring project. Airpost is licensed under GPL-3.0-only.