Airpost
AI and plugins

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

The files

examples/service-plugin
package.json
Cargo.toml
src
main.rs
bin
airpost-sample-service

package.json declares the service; bin/ holds the built binary it points at:

examples/service-plugin/package.json
{
  "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:

macOS
tail "<profile>/services/airpost-sample-service/service.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:

  1. Options. AIRPOST_CONFIG_DIR and AIRPOST_SERVICE_PACKAGE, which the unit sets, give the profile and the plugin id. --config-dir and --plugin-id override them.
  2. Connect. airpost_client::Engines::connect finds 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.
  3. Subscribe. It subscribes to Thread and Message deltas and reads notifications until the connection ends.
  4. Find due rows. For each metadata-expiration delta, it looks in each model’s metadata array for the entry whose pluginId is its own and whose value.expiration has 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.
  5. Act. It queues three tasks with task.queue: star the thread, mark it unread, and write the metadata back without expiration (with firedAt instead), 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.new notifications to act on arriving mail instead of due metadata.
  • Set metadata with an expiration from your plugin’s UI (or airpost task queue as 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 run airpost service install again.

Cleanup

airpost service uninstall airpost-sample-service

Then remove the plugin in Preferences > Plugins.