Airpost
Customize

Plugins

The plugins that ship with Airpost, how to install your own, and plugins that run background services.

Many Airpost features are plugins that ship with the app and load the same way third-party plugins do. A plugin is a folder with a package.json and a lib/main entry point. It runs in the app’s windows, adds UI through the component registry, and works with the same mail data the rest of the app uses. A plugin can also bring a small background program, a service plugin, that keeps running while the app is closed.

Bundled plugins

These ship in the app’s plugins folder.

PluginWhat it doesRuns where
AIThread summaries, reply suggestions and inbox sorting. See AI features.UI in the app; model calls in the engine
Send LaterSchedule messages. See Scheduling.Schedule kept and sent by the engine
Send RemindersBring a thread back if nobody replies.Engine
Thread SnoozeSnooze threads until later.Engine
Composer TemplatesReusable messages. See Templates.App
Grammar checkGrammar checking in the composer with a LanguageTool-compatible server.Requests made by the engine
TranslationTranslate drafts and incoming mail with LibreTranslate or DeepL.Requests made by the engine
Phishing detectionWarns when the reply-to address isn’t the sender’s.App
Participant profileDetails about the people in a thread, with optional People Data Labs lookups.App and engine
Activity, Open tracking, Link tracking, Thread sharingNeed an Airpost server; not available yet.

Scheduling, reminders and snooze are executed by the engine, which is why they still happen when the window is closed, and why you can drive them from the CLI too (airpost snooze, airpost remind). See Local features.

Built into the app, outside the plugins list, are features such as tracking-pixel removal, list unsubscribe, the system tray, undo and the theme picker.

Install a plugin

Plugins run inside the app and have the same access to your email data as Airpost. Only install plugins from developers you trust, and read the code if you can.

Get the plugin folder

Download or clone the plugin. It must be a folder with a package.json. If it’s written in TypeScript or needs building, follow its README first.

Install it

In Preferences > Plugins, click Install from a folder…, or use Developer > Install a Plugin. Pick the folder.

Check it loaded

The plugin is enabled right away, with no restart. It shows up in Preferences > Plugins with its version and Installed from (where it came from).

Installed plugins live in the packages folder of your profile. To remove one, remove it in Preferences > Plugins, or quit Airpost and delete its folder from packages.

Mailspring plugins

Airpost started as a fork of Mailspring, and keeps the plugin API Mailspring plugins use (mailspring-exports, mailspring-component-kit, component registry roles, stores and tasks). Many Mailspring plugins load without changes. Plugins that reach into the old sync process directly, or depend on Mailspring’s own servers, may not work.

Plugins with background services

Some plugins need to do work when nobody has Airpost open: act on a reminder at 3am, watch a folder, push to another tool. These declare a service binary in their package.json:

{
  "name": "airpost-sample-service",
  "engines": { "airpost": "^1.27.0" },
  "airpost": {
    "service": { "bin": "bin/airpost-sample-service" }
  }
}

The service runs as a separate program under launchd (macOS) or systemd --user (Linux), after the engine, and talks to the engine like any other client.

Set up a service

Open Preferences > Plugins > Background services

Plugins with a service are listed with a status: running, installed but not running, Not active, or Service needs attention (for example when its unit file is missing).

Click Set up service…

Airpost shows the plan before writing anything: the binary it will copy, its SHA-256, where the copy goes, and the full unit file it will install. If the engine isn’t installed as a background service yet, the plan includes the engine’s unit too, since the service needs the engine to reach your mail.

Click Install service

Airpost copies the binary into your profile, writes the units and starts the service. You see “Service installed and started”, or “It starts the next time you log in”.

Airpost runs the copy, not the file in the plugin folder, and records its hash. Changing the plugin folder afterwards doesn’t change what runs until you set the service up again. Remove service stops it and deletes the unit and the binary copy.

From the command line

The same install is available from the CLI, which is useful on a server with no desktop:

# See exactly what would be written, without writing it
airpost service install airpost-sample-service --dry-run

# Install, refusing if anything differs from the dry run
airpost service install airpost-sample-service --expect-plan <planSha256>

# What's installed: source, binary, hash and unit
airpost service list

airpost service uninstall airpost-sample-service

Use --package-dir to install from a folder instead of the profile, and --expect-sha256 to pin the binary hash. See Background services.

If a plugin breaks the app

Start Airpost with the --safe flag. It skips plugins in your profile’s packages folder and loads only the bundled ones, so you can remove the one causing trouble.

On macOS, run open -a Airpost --args --safe from a terminal. On Linux, add --safe to the command that starts the app.

Background services aren’t affected by --safe, since they don’t run in the app. Remove a misbehaving one with Remove service or airpost service uninstall. See Troubleshooting.

Writing plugins

To write a plugin, see Plugins for developers. The examples/service-plugin folder in the repository is a working service plugin in Rust that stars and marks unread a thread when its reminder comes due, also while Airpost is closed.