Airpost
How Airpost works

The engine

One process for all your accounts, the local socket clients attach to, detached mode, and the engine's lifecycle.

airpost-engine is the program that does all of Airpost’s mail work. It syncs your accounts, holds their credentials, owns the database and search index, and runs every change you make. The desktop app, the airpost command, airpost-mcp and airpost-gateway are clients of it: they don’t open the database or talk to your mail server themselves.

This page explains how the engine is organised and how clients attach. For commands and flags, see The engine in the CLI tab.

One process, all accounts

Clients use the engine in serve mode (airpost-engine --mode serve). It starts with no account, binds its socket, and then runs every account you add in the same process.

Each account runs in its own runtime with its own threads, its own stream of changes and its own log file, engine-<accountId>.log. The main threads of an account are:

ThreadWhat it does
mainRuns the local phase of tasks you queue and answers account-scoped requests.
backgroundLists folders and labels, scans folders for changes, and sweeps messages that disappeared from the server.
foregroundHolds IMAP IDLE on the inbox, fetches bodies, runs the remote phase of tasks, and pushes drafts.
calContactsSyncs calendars and contacts on a fixed schedule.
metadataExpirationFires snoozes, scheduled sends and reminders when they come due.
mailRulesApplies your mail rules to arriving mail.
metadataPulls plugin metadata from an Airpost server. Only started when one is connected.

Engine-wide threads handle the socket, stdin and signals, and a liveQueries thread keeps clients’ live queries up to date.

When an account fails

A failure on one of an account’s threads (a non-retryable error, a database error while applying a task, or a crash) stops that account alone. The engine sends account.state with stopped and the error to every client, and the other accounts keep syncing.

What happens next depends on why it stopped:

  • Refused credentials. The account stays stopped with authFailed until you sign in again.
  • Anything else. The engine starts it again after a backoff and reports when (retryAt). Five stops within five minutes stop it for good, until it’s added again.

A crash on an engine-wide thread (the socket, stdin or signals) ends the whole process.

The socket

The engine listens on a Unix domain socket and writes a discovery file next to it:

PathWhat it is
<profile>/run/engine.sockThe engine protocol.
<profile>/run/engine.jsonThe engine’s pid, socket and accounts, plus detached: true for a detached engine. Rewritten when accounts are added or removed.

The run/ directory is created with mode 0700, and the engine accepts a connection only when the peer’s user id matches its own. See Security model.

Clients find the engine by reading the discovery files in <profile>/run/. A file whose process is gone and whose socket doesn’t answer is treated as left over from a crash and skipped. The airpost command exits with code 3 when it finds no live engine.

The protocol

The protocol is JSON-RPC 2.0, one JSON object per line (NDJSON). The types are defined in the airpost-ipc crate, which also produces a JSON Schema that @airpost/client generates its TypeScript types from. The current protocol version is 1.

hello

The first request on every connection. The client names itself and the protocol version; the engine answers with its version, pid, accounts, whether it’s detached, and a features list such as snooze, unsubscribe, draft-pipeline and expiration-executor. Clients check features instead of version numbers.

Reads and live queries

threads.list, messages.get, folders.list, query and the rest return data. query.subscribe keeps a query live: the engine re-runs it when matching rows change, at most every 50 ms, and sends query.changed with the rows that entered or changed.

Changes

Intents such as threads.archive, threads.snooze or draft.send, or a raw task.queue. The engine replies once it has applied the local phase, and reports progress through deltas and task.done.

subscribe

Opts the connection into delta notifications: every model the engine saves or removes, filtered by account and class if you ask.

A request without an id is a notification, which the engine accepts and doesn’t answer. Batches aren’t supported. Slow calls (AI, integrations, file downloads and some reads) run on worker pools and can answer out of order; when a pool’s queue is full the engine answers “busy” at once instead of queueing forever.

{"jsonrpc":"2.0","id":1,"method":"hello","params":{"protocol":1,"client":"my-script"}}
{"jsonrpc":"2.0","id":1,"result":{"protocol":1,"engine":"…","pid":4242,"accounts":[…],"features":["snooze","unsubscribe",…],"detached":false}}

A subscriber that stops reading and lets its queue fill is sent disconnect and closed, so one stuck client can’t slow the engine down for the others.

Clients attaching

In the desktop app, the main process starts the engine and keeps a pipe to its stdin and stdout. That pipe is the control channel for the calls that carry credentials or manage the engine, such as account.add, engine.resetDatabase and engine.shutdown. Secrets go one way: from the client to the engine. The engine never sends a password back over the socket.

Each app window opens its own socket connection for reads, live queries and tasks. The CLI, airpost-mcp and the gateway connect the same way. Everything a connection does acts as you, because only you can open the socket.

Detached mode

A detached engine (airpost-engine --mode serve --detached) has no parent. It’s what the background service runs, and what a server runs. The differences:

  • There’s no stdin control channel. Local, non-relayed socket connections can call the engine methods that the parent would otherwise send (account management, engine.shutdown and the like), except credentials.import.
  • Nothing secret is written to stdout, which is a terminal or a service log.
  • engine.json and hello say detached: true.

When the desktop app starts and finds a detached engine of the same build, it joins it instead of starting its own. If the running engine is a different build installed as a unit, the app restarts the unit first; any other engine is asked to stop.

Lifecycle

  • Started by the app. When no engine is running, the desktop app starts one with pipes. If its stdin stays closed for more than 30 seconds (the app went away), the engine exits with code 141.
  • Started as a service. With Keep Airpost running in the background on, or after airpost engine install, launchd or systemd runs a detached engine at login and restarts it after a failed exit. The unit is written so it doesn’t fight the app’s own engine for the socket. See Background services.
  • Not socket-activated. The engine syncs with no client connected, so it has to be running already. The gateway and the MCP HTTP server are socket-activated; the engine isn’t.
  • One per profile. A second engine on the same profile would find the socket taken. Use --config-dir (or CONFIG_DIR_PATH) for a separate profile.

Other modes

serve is the only mode clients use. The others exist for setup and debugging: sync (one account, the original Mailspring-Sync interface), test (check an account’s settings), migrate, reset, install-check and import-legacy (bring over a Mailspring profile). The flags are in The engine.