Airpost
Terminal and scripting

Watch and notify

Stream new mail with airpost watch --json and turn it into desktop notifications or webhook calls.

What you’ll build

A small long-running script that listens to airpost watch --new-mail --json, looks up each new message, filters it, and sends a desktop notification or a JSON POST to a webhook (Slack, ntfy, your own service). Because it reads the engine’s stream, it reacts within seconds of the message syncing and works with the desktop app closed.

Prerequisites

  • airpost on your PATH. See Install the CLI.
  • An engine running without the desktop app: airpost engine install.
  • jq 1.6 or later, and curl for webhooks.
  • For desktop notifications: macOS (osascript) or Linux with notify-send.

Look at the stream

airpost watch --new-mail --json

Leave it running and send yourself a message. Each new unread inbox message prints one line:

{"event":"mail.new","accountId":"54500b8c","threadId":"t_8a1...","messageId":"m_c42..."}

If an engine goes away, the stream prints a disconnect line and exits 1:

{"event":"disconnect","pid":51838,"reason":"the engine closed the connection: ..."}

Write the notifier

~/bin/airpost-notify
#!/usr/bin/env bash
# Notify on new mail. Set WEBHOOK_URL to POST JSON instead of (or as well as)
# showing a desktop notification. NOTIFY_FROM is an optional regex on the sender.
set -uo pipefail

WEBHOOK_URL="${WEBHOOK_URL:-}"
NOTIFY_FROM="${NOTIFY_FROM:-.}"
DESKTOP="${DESKTOP:-1}"

notify_desktop() {  # title, text
  if command -v osascript >/dev/null; then
    osascript -e 'on run argv
      display notification (item 2 of argv) with title (item 1 of argv)
    end run' "$1" "$2"
  elif command -v notify-send >/dev/null; then
    notify-send "$1" "$2"
  fi
}

handle() {  # message id
  local msg from name subject snippet
  msg=$(airpost show "$1" --json) || return
  from=$(jq -r '.message.from[0].email // ""' <<<"$msg")
  name=$(jq -r '.message.from[0].name // .message.from[0].email // "?"' <<<"$msg")
  subject=$(jq -r '.message.subject // ""' <<<"$msg")
  snippet=$(jq -r '.message.snippet // ""' <<<"$msg")

  grep -Eqi -- "$NOTIFY_FROM" <<<"$from" || return 0

  [ "$DESKTOP" = "1" ] && notify_desktop "$name" "$subject"
  if [ -n "$WEBHOOK_URL" ]; then
    jq -n --arg from "$from" --arg name "$name" --arg subject "$subject" \
          --arg snippet "$snippet" --arg id "$1" \
          '{text: "\($name): \($subject)", from: $from, subject: $subject,
            snippet: $snippet, messageId: $id}' |
    curl -fsS -m 10 -H 'Content-Type: application/json' -d @- "$WEBHOOK_URL" >/dev/null ||
      echo "webhook failed for $1" >&2
  fi
}

while true; do
  airpost watch --new-mail --json |
    jq --unbuffered -r 'select(.event == "mail.new") | .messageId' |
    while read -r id; do handle "$id"; done
  echo "watch ended; restarting in 5s" >&2
  sleep 5
done
chmod +x ~/bin/airpost-notify

Try it

NOTIFY_FROM='@acme\.example$' ~/bin/airpost-notify

Send yourself a message from an address at acme.example; a notification shows with the sender’s name and the subject.

For Slack, use an incoming webhook URL; Slack reads the text field and ignores the rest:

DESKTOP=0 WEBHOOK_URL=https://hooks.slack.com/services/T000/B000/XXXX ~/bin/airpost-notify

Keep it running

~/Library/LaunchAgents/com.example.airpost-notify.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.example.airpost-notify</string>
  <key>ProgramArguments</key>
  <array><string>/Users/you/bin/airpost-notify</string></array>
  <key>EnvironmentVariables</key>
  <dict>
    <key>PATH</key>
    <string>/Users/you/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
  </dict>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardErrorPath</key><string>/tmp/airpost-notify.log</string>
</dict>
</plist>
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.airpost-notify.plist

Expected output

A desktop notification titled with the sender’s name and showing the subject. On the webhook side, a POST body like:

{
  "text": "Dana Ruiz: Contract redlines",
  "from": "dana@acme.example",
  "subject": "Contract redlines",
  "snippet": "Hi, attached are the revised redlines. Could you look at section 4...",
  "messageId": "m_c42..."
}

How it works

airpost watch subscribes to every running engine. With --new-mail it subscribes to no model classes, so the only lines are mail.new events: one per message that lands unread in the inbox. The event carries accountId, threadId and messageId and nothing else, so the script calls airpost show <message-id> --json for the message’s from, subject and snippet.

jq --unbuffered matters: without it jq holds lines back and notifications arrive in bursts. The outer while true loop restarts the watch after a disconnect, for example when the engine restarts after an upgrade.

Variations

  • One account. airpost watch --new-mail --json -a you@work.com.

  • Other changes. Drop --new-mail and use -c Task to see the engine’s task queue, or -c Thread for every thread change. Those lines have no event key; they carry modelClass, type (persist, unpersist, metadata-expiration) and modelJSONs.

    airpost watch -c Task --json | jq --unbuffered -c '.modelJSONs[] | {cls: .__cls, status}'
    
  • Star VIPs automatically. In handle, run airpost star "$(jq -r .message.threadId <<<"$msg")" for matching senders. For rules that need no script, see airpost rules add.

  • ntfy. curl -d "$name: $subject" https://ntfy.sh/your-topic in place of the JSON POST.

Cleanup

launchctl bootout gui/$(id -u)/com.example.airpost-notify && rm ~/Library/LaunchAgents/com.example.airpost-notify.plist
# Linux
systemctl --user disable --now airpost-notify && rm ~/.config/systemd/user/airpost-notify.service
rm ~/bin/airpost-notify