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.
| Plugin | What it does | Runs where |
|---|---|---|
| AI | Thread summaries, reply suggestions and inbox sorting. See AI features. | UI in the app; model calls in the engine |
| Send Later | Schedule messages. See Scheduling. | Schedule kept and sent by the engine |
| Send Reminders | Bring a thread back if nobody replies. | Engine |
| Thread Snooze | Snooze threads until later. | Engine |
| Composer Templates | Reusable messages. See Templates. | App |
| Grammar check | Grammar checking in the composer with a LanguageTool-compatible server. | Requests made by the engine |
| Translation | Translate drafts and incoming mail with LibreTranslate or DeepL. | Requests made by the engine |
| Phishing detection | Warns when the reply-to address isn’t the sender’s. | App |
| Participant profile | Details about the people in a thread, with optional People Data Labs lookups. | App and engine |
| Activity, Open tracking, Link tracking, Thread sharing | Need 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.