Airpost
How Airpost works

Profiles and data

The profile directory, the database, what's stored where, secrets and the keychain, logs, and how to back up, restore or move to a new machine.

Everything Airpost keeps on your computer lives in one profile directory, except your passwords and tokens, which live in your OS keychain. Every program uses the same profile by default, so the desktop app, the airpost command, agents and the gateway all see the same mail and settings.

For a short user-facing version, see Data and files.

Where the profile is

PlatformLocation
macOS~/Library/Application Support/Airpost
Linux~/.config/Airpost (or $XDG_CONFIG_HOME/Airpost)
Linux snapThe snap’s $SNAP_USER_COMMON folder
Server imageThe profile volume

The engine reads the profile path from CONFIG_DIR_PATH, and the CLI from --config-dir. Pointing them at another directory gives you a separate, independent profile with its own engine, which is useful for testing. Airpost’s profile is separate from Mailspring’s, so both can run side by side.

What’s inside

PathOwnerContents
airpost.dbEngineThe SQLite database: messages, threads, folders, labels, bodies, the search index, calendars, contacts, tasks and plugin metadata. Runs in WAL mode, so airpost.db-wal and airpost.db-shm sit next to it.
accounts.jsonEngineYour accounts and their server settings, without secrets.
settings.jsonEngineSettings the engine and every client share: signatures, templates list, mail rules, undo-send delay, AI and integration options. Rewritten atomically on each change.
server.jsonEngineThe Airpost server connection, when you have one.
run/Engineengine.sock and the engine.json discovery file. Private to your user.
engine.log, engine-<accountId>.logEngineLogs, below.
pending-sends/EnginePer-recipient bodies for sends waiting out their undo window.
secrets.encEngineThe encrypted secret store, only when a key file is used.
config.jsonDesktopDesktop preferences.
keymap.jsonDesktopShortcuts you changed.
templates/DesktopYour templates, one file each.
packages/DesktopPlugins and themes you installed.
mcp.json, mcp-token, mcp-audit.logairpost-mcpAgent access policy, the HTTP bearer token, and the log of what agents did. See Agents.
gateway/devices.jsonairpost-gatewayPaired browsers, as hashes of their tokens.
services/airpostService plugin binaries and their logs.

No client reads airpost.db directly. They ask the engine, which is why the CLI and agents see the same data the app does and can’t corrupt it.

The database

airpost.db is a cache of what’s on your provider, plus the things only Airpost knows: tasks not yet sent to the server, plugin metadata (snoozes, scheduled sends, reminders), local-only drafts, and draft tombstones. The schema starts from the Mailspring-Sync schema (version 12) and adds Airpost’s migrations, which the engine applies at start.

Because mail is a cache, you can always rebuild it:

WhatWhereEffect
Rebuild one accountPreferences > Accounts > the account > Rebuild…Downloads that account’s mail again.
Rebuild everythingPreferences > Advanced > Rebuild the mail databaseDownloads mail for every account again. Accounts and settings stay.
ResetPreferences > Advanced > Reset Airpost…Removes all accounts and settings. Mail on your providers isn’t touched.

A rebuild loses what exists only locally: unsent tasks, local-only drafts, and scheduled sends and snoozes that haven’t synced to an Airpost server. Let pending work finish first.

Secrets

Account passwords, OAuth refresh tokens, integration and AI keys and the Airpost server token are held by the engine as one keyset in one item, so a keychain asks for permission at most once. The airpost-secrets crate has three backends:

The Keychain, as a generic password with the service name Airpost Engine.

There’s no plaintext backend. If none of these is available, the engine can’t store secrets. A keyset that exists but can’t be read (a locked keychain, a wrong key) is an error, never an empty keyset, so a later write can’t wipe your passwords.

Secrets go one way. Clients hand them to the engine (account.add, secrets.set); nothing reads them back over the socket. See Security model.

Logs

LogWhat’s in it
engine.logThe engine as a whole: start, accounts added and stopped, socket errors.
engine-<accountId>.logOne account’s sync, tasks and protocol summaries. Rotated to .log.1 up to .log.3.
launchd-engine.logmacOS only: the engine unit’s stdout and stderr.
mcp-audit.logEach agent tool call.

Only info level and above is recorded. With --verbose IMAP and SMTP traffic is logged too, but authentication payloads never are. airpost logs engine, airpost logs <account> and airpost logs -f read them; Developer > Open Engine Logs opens the folder.

Back up and restore

Your mail is on your provider, so a backup is about the rest: accounts, settings, templates, rules, plugins and anything local-only.

Stop everything

Quit the app. If the background engine is on, run airpost engine stop. Copying the database while the engine writes to it can give you a copy that doesn’t open.

Copy the profile

Copy the whole directory, including airpost.db-wal if it’s there. You can leave out run/ and the logs.

Keep the key separately

With the file store, secrets.enc is useless without its key file. Back up the key somewhere other than the profile backup, or the backup alone is enough to read your credentials.

To restore, stop Airpost, put the directory back, and start it. With the OS keychain on the same computer, nothing else is needed.

Moving to a new computer

Two approaches work:

  • Start fresh. Install Airpost and add your accounts again. Mail downloads from your providers. Copy templates/, packages/ and keymap.json over if you want them.
  • Copy the profile. Copy the stopped profile to the same location on the new computer. Your settings, rules and account list come along. Secrets stored in the OS keychain stay on the old computer, so expect to sign in to each account again. With the file store, copy the key file too.

You can also delete airpost.db on the new machine before the first start to download a clean copy instead of carrying over the cache.