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
airposton yourPATH. See Install the CLI.- An engine running without the desktop app:
airpost engine install. jq1.6 or later, andcurlfor webhooks.- For desktop notifications: macOS (
osascript) or Linux withnotify-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
#!/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
<?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-mailand use-c Taskto see the engine’s task queue, or-c Threadfor every thread change. Those lines have noeventkey; they carrymodelClass,type(persist,unpersist,metadata-expiration) andmodelJSONs.airpost watch -c Task --json | jq --unbuffered -c '.modelJSONs[] | {cls: .__cls, status}' -
Star VIPs automatically. In
handle, runairpost star "$(jq -r .message.threadId <<<"$msg")"for matching senders. For rules that need no script, seeairpost rules add. -
ntfy.
curl -d "$name: $subject" https://ntfy.sh/your-topicin 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