Scripting with jq
Answer questions about your mail and change it in bulk by piping airpost --json through jq.
What you’ll build
A set of one-liners and two small scripts that use airpost --json with jq: counting, finding your noisiest senders, exporting a CSV, saving attachments in bulk and archiving safely with a dry run first. Each one only uses fields the CLI prints.
Prerequisites
airposton yourPATH. See Install the CLI.- An engine running.
jq1.6 or later.
The shapes you’ll use
| Command | Top-level JSON |
|---|---|
airpost search, airpost threads | {"threads": [...]} (threads also has next, more) |
airpost show <thread-id> | {"kind": "thread", "thread": {...}, "messages": [...]} |
airpost show <message-id> | {"kind": "message", "message": {...}, "body", "files"} |
airpost folders | {"folders": [...], "counts": {"<id>": {"total", "unread"}}} |
archive, trash, move, … | {"action", "dryRun", "accounts": [...], "taskIds", "undo"} |
Threads carry id, aid (account id), subject, participants ({name, email}), unread, starred, attachmentCount, folders, labels, and lmt/lmrt/lmst timestamps in Unix seconds. Messages carry id, threadId, hMsgId, subject, snippet, date, from, to, cc, files and unread. Look at a real document before you rely on a field:
airpost search 'in:inbox' -n 1 --json | jq '.threads[0]'
Count and group
Unread inbox threads per account:
airpost search 'in:inbox is:unread' -n 500 --json \
| jq -r '.threads | group_by(.aid)[] | "\(.[0].aid)\t\(length)"'
Top 10 senders in the inbox over the last month:
airpost search 'in:inbox after:1m' -n 1000 --json \
| jq -r '[.threads[].participants[0].email] | group_by(.)
| map({email: .[0], n: length}) | sort_by(-.n)[:10][]
| "\(.n)\t\(.email)"'
Unread counts per folder, with names:
airpost folders --json \
| jq -r '.counts as $c | .folders[]
| select(($c[.id].unread // 0) > 0)
| "\($c[.id].unread)\t\(.path)"'
Export a CSV
airpost search 'from:billing@ has:attachment after:2026-01-01' -n 500 --json \
| jq -r '["date","from","subject","thread_id"],
(.threads[] | [ (.lmrt | todate),
(.participants[0].email // ""),
.subject, .id ])
| @csv' > invoices.csv
Save every attachment from a search
#!/usr/bin/env bash
# Usage: save-attachments.sh 'from:accountant has:attachment after:3m' ./out
set -euo pipefail
query="$1"; dir="${2:-.}"
airpost search "$query" -n 200 --json | jq -r '.threads[].id' |
while read -r thread; do
airpost show "$thread" --json \
| jq -r '.messages[] | select((.files | length) > 0 and (.draft | not)) | .id'
done |
while read -r msg; do
airpost attachment save "$msg" --dir "$dir"
done
attachment save downloads attachments that aren’t stored yet and prints each saved path. It won’t replace an existing file unless you add --force.
Change threads in bulk, safely
Check what a query takes, then act, then keep the undo token:
q='from:notifications@github.com before:14d'
airpost archive -q "$q" --dry-run --json | jq '.threads | length'
token=$(airpost archive -q "$q" --wait --json | jq -r '.undo')
echo "undo with: airpost undo $token"
Act on ids you picked with jq instead of a query. This marks read every unread inbox thread whose only participant is a no-reply address:
airpost search 'in:inbox is:unread' -n 500 --json \
| jq -r '.threads[] | select(all(.participants[]; .email | test("no-?reply"; "i"))) | .id' \
| xargs -r airpost mark-read --wait
Expected output
The sender report prints a tab-separated list:
41 notifications@github.com
17 news@substack.com
9 dana@acme.example
The bulk archive prints a count, then the undo hint:
63
undo with: airpost undo 3f9c2a...
How it works
airpost connects to the running engine’s socket and prints the engine’s own JSON models, so field names follow the engine (aid, lmrt, hMsgId). Errors go to stderr as one airpost: ... line, also with --json, so a pipe never gets half a document. Check exit codes in scripts: 1 for a command that ran and failed, 2 for a usage error, 3 when no engine is running.
A query matching more than 500 threads is refused by the thread actions unless you pass -n, which takes at most that many, newest first.
Variations
- Page through a folder.
airpost threads --role inbox --all --jsonpages through every thread; with one account,nextis the cursor. - Raw engine calls.
airpost rpc <method> '<params>'prints the result of any engine method, for things without a command yet. - Stream instead of poll. See Watch and notify.
Cleanup
Nothing to remove. airpost undo --list shows recent changes if you want to take one back.