Build a service plugin
Walk through examples/service-plugin end to end: build it, install it as a background service, trigger it, and read how it works.
What you’ll build
The sample “remind me” service from examples/service-plugin, running as a launchd or systemd user unit next to the engine. When a thread’s airpost-sample-service metadata reaches its expiration, the service stars the thread, marks it unread and clears the expiration, whether Airpost is open or not. Once it works, you’ll know the pieces to write your own.
Prerequisites
- A checkout of the repository and a Rust toolchain. See Building from source.
airposton yourPATH, and an engine running. See Install the CLI.
The files
examples/service-plugin
src
bin
package.json declares the service; bin/ holds the built binary it points at:
{
"name": "airpost-sample-service",
"displayName": "Sample service",
"version": "0.1.0",
"engines": { "airpost": "^1.27.0" },
"airpost": {
"service": {
"bin": "bin/airpost-sample-service"
}
}
}
Build the binary
From the repository root:
cargo build --release -p airpost-sample-service
mkdir -p examples/service-plugin/bin
cp target/release/airpost-sample-service examples/service-plugin/bin/
Run it by hand first
airpost-sample-service --config-dir "<profile>"
Use your profile path (~/Library/Application Support/Airpost on macOS, ~/.config/Airpost on Linux). It prints one JSON line per event:
{"event":"connected","pid":51838,"pluginId":"airpost-sample-service"}
Stop it with Ctrl-C.
Install the plugin
In Airpost, open Preferences > Plugins, choose Install from a folder… and pick examples/service-plugin.
Install its service
Look at what would be written, then install:
airpost service install airpost-sample-service --dry-run
airpost service install airpost-sample-service
airpost service list
The dry run prints the binary, its SHA-256 and the unit text. To make sure the install writes exactly what you reviewed, pass the hash back with --expect-sha256 <hex>. The desktop’s Set up service… button on the plugin does the same.
If the plugin isn’t installed in the profile, point at the folder instead: --package-dir examples/service-plugin.
Trigger it
Pick a thread and give it a reminder one minute from now:
thread=$(airpost search 'in:inbox' -n 1 --json | jq -r '.threads[0].id')
airpost task queue '{"__cls": "SyncbackMetadataTask", "modelId": "'"$thread"'",
"modelClassName": "thread", "pluginId": "airpost-sample-service",
"value": {"expiration": '$(( $(date +%s) + 60 ))'}}'
Quit Airpost if you like, and wait a minute.
Check the result
airpost show "$thread"
The thread is starred and unread. The service’s log:
Expected output
{"event":"connected","pid":51838,"pluginId":"airpost-sample-service"}
{"event":"acted","accountId":"54500b8c","modelClass":"Thread","modelId":"t_8a1...","threadId":"t_8a1...","expiration":1794823260}
Without an engine it prints {"event":"waiting","configDir":"..."} once and keeps retrying; after the engine restarts it prints {"event":"disconnected","pid":...} and connects again.
How it works
src/main.rs is about 230 lines:
- Options.
AIRPOST_CONFIG_DIRandAIRPOST_SERVICE_PACKAGE, which the unit sets, give the profile and the plugin id.--config-dirand--plugin-idoverride them. - Connect.
airpost_client::Engines::connectfinds the engine through the profile’s discovery files. With none running it waits, backing off from 1 to 30 seconds; launchd has no start order, so the service may start before the engine. - Subscribe. It subscribes to
ThreadandMessagedeltas and reads notifications until the connection ends. - Find due rows. For each
metadata-expirationdelta, it looks in each model’smetadataarray for the entry whosepluginIdis its own and whosevalue.expirationhas passed. Other plugins’ rows in the same delta are left alone. The engine resends due rows on every scan until the expiration is cleared, so the service remembers each (model, expiration) pair it handled. - Act. It queues three tasks with
task.queue: star the thread, mark it unread, and write the metadata back withoutexpiration(withfiredAtinstead), which stops the engine announcing it.
No plugin code runs inside the engine: the service is a separate program on <profile>/run/engine.sock, speaking JSON-RPC 2.0 over newline-delimited JSON. Rust services use airpost-client and airpost-ipc; any language that can open a Unix socket works.
Making it your own
- Copy the folder, rename the package and the binary, and use your package name as the plugin id.
- Use
mail.newnotifications to act on arriving mail instead of due metadata. - Set metadata with an
expirationfrom your plugin’s UI (orairpost task queueas above) to schedule work. - A service runs at login with your rights. Installing copies the binary to
<profile>/services/<package>/, so rebuilding changes nothing until you runairpost service installagain.
Cleanup
airpost service uninstall airpost-sample-service
Then remove the plugin in Preferences > Plugins.