Airpost
The airpost command

JSON and scripting

--json output, exit codes, streaming with watch, and examples with jq.

Add --json to any command for machine-readable output. A command prints one JSON document on stdout; a stream (watch, logs) prints NDJSON, one JSON object per line.

airpost threads --role inbox -n 5 --json | jq -r '.threads[] | "\(.id)\t\(.subject)"'

Errors and exit codes

Errors go to stderr as one line of text starting airpost: , also with --json. Check the exit code rather than parsing stderr.

CodeMeaning
0OK
1The command ran and failed (a failed send with --wait, a missing id, a draft validate error)
2Usage error: bad flags or a combination that can’t be done
3No engine running

airpost status --json exits 3 when no engine is running but still prints its document, with engines empty and the installed services, so you can check both at once.

Commands that would ask for confirmation (account remove, account resync, folder empty) refuse to run with --json or without a terminal unless you pass -y/--yes.

Output shapes

Models are the engine’s JSON as stored, with every field. Field names follow the engine’s conventions: id, aid (account id), __cls (model class), v (version), timestamps in Unix seconds. The shapes below list the top-level keys. The command reference documents each command’s document in more detail, write commands included; inspect a real document with jq for the rest.

statusobject

{"engines": [...], "services": [...], "skills": [...]}. Each engine has accounts (with accountId, email, state, connectionError and the account model), build and capabilities. Each service has name (engine, gateway, mcp-http), installed, running, pid, unit, bin, owner, url, port, onDemand and warnings.

accountsobject

{"accounts": [{"accountId", "email", "state", "error", "pid", "socket"}]}

threadsobject

{"threads": [...], "next": <cursor|null>, "more": <bool>}. Each thread has id, aid, subject, participants, unread, starred, attachmentCount, folders, labels and the lmt/lmrt/lmst last-message timestamps. next is set only when one account is listed; more says whether there are more either way.

searchobject

{"threads": [...]}, threads as above.

folders, labelsobject

{"folders": [...], "counts": {"<id>": {"total", "unread"}}} (or labels).

showobject

With a thread id: {"kind": "thread", "thread": {...}, "messages": [...]}, messages without bodies. With a message id: {"kind": "message", "message": {...}, "body", "files"}; body is filled with --body.

draft new, reply, reply-all, forward, editobject

{"draft": {...}, "updated": <bool>}. updated is true when an existing draft was revised (--prefer-existing).

draft listobject

{"drafts": [...]}: message models with id, threadId, hMsgId (Message-ID), subject, from, to, cc, bcc, files, date.

draft scheduledobject

{"scheduled": [...]}

thread actionsobject

archive, trash, move, mark-read and the rest print {"action", "dryRun", "accounts": [{"accountId", "email", "threadIds", "unchangedThreadIds"}], "taskIds", "undo"}. With --dry-run there is also threads. Pass undo to airpost undo <token>.

snooze, unsnoozeobject

{"accounts": [{"accountId", "threadIds", "taskIds", "undo"}], "until"}

task listarray

A bare array of task models (id, aid, __cls, status, …).

calendarsobject

{"calendars": [...]}: calendar models as stored, each with the account’s email added.

calendar listobject

{"occurrences": [...]}, with eventId, title, start/end (Unix seconds) or startDate/endDate for all-day events, organizer, attendees and myStatus.

contacts, contact getobject

{"contacts": [...]}; contact get prints {"contact", "metadata", "data"}.

ai summarize, ai usageobject

{"text", "model", "cached", "usage"}; ai usage is a bare array of {"day", "provider", "feature", "inputTokens", "outputTokens", "requests"}.

tracking list, tracking linksobject

{"messages": [...]} with opens and links per message; {"links": [{"url", "clickCount", "uniqueRecipients", ...}]}.

service commandsobject

install prints the unit it wrote (service, installed, bin, sha256, path, text, …). start, stop, restart and uninstall print {"service", "name", "path", ...}.

undo --listobject

{"entries": [...]}

settings getobject

{"values": {"<key>": <value>}}

rules list, template list, signature listobject

{"rules": [...]}, {"templates": [{"id", "name", "subject", "variables", "preview"}]}, {"signatures": [...], "defaults": {"<address>": "<signature id>"}}.

Watch

airpost watch --json streams NDJSON until you interrupt it. Three kinds of line:

{"accountId":"54500b8c","seq":812,"modelClass":"Thread","type":"persist","modelJSONs":[{...}]}
{"event":"mail.new","accountId":"54500b8c","threadId":"...","messageId":"..."}
{"event":"disconnect","pid":51838,"reason":"..."}
  • A delta has no event key. type is persist, unpersist or metadata-expiration, and modelJSONs holds the changed models.
  • mail.new is one message that landed unread in the inbox. It’s printed whatever --class says.
  • disconnect means an engine went away. The watch then exits 1, because a stream missing an account’s changes would look complete.

Limit deltas with -c/--class (repeatable), or print only new mail with --new-mail.

# Print the subject of each new message as it arrives
airpost watch --new-mail --json \
  | jq --unbuffered -r 'select(.event == "mail.new") | .messageId' \
  | while read -r id; do airpost show "$id" --json | jq -r '.message.subject'; done

Logs

airpost logs --json prints {"line": "..."} per log line, and keeps streaming with -f.

Examples

Archive newsletters older than a month, checking first:

airpost archive -q 'from:news@example.com before:30d' --dry-run --json | jq '.threads | length'
airpost archive -q 'from:news@example.com before:30d' --wait --json | jq -r '.undo'

Unread count per account:

airpost search 'is:unread in:inbox' -n 500 --json \
  | jq -r '.threads | group_by(.aid)[] | "\(.[0].aid)\t\(length)"'

Write a reply from a file and send it, failing the script if it doesn’t go:

id=$(airpost draft reply "$THREAD_ID" --body-file reply.txt --json | jq -r '.draft.id')
airpost draft send "$id" --wait --timeout 120

Send tomorrow morning with a reminder:

airpost draft send "$id" --at 'tomorrow 9:00' --remind-in 3d

Wait for the engine before a script runs:

until airpost status --json >/dev/null 2>&1; do sleep 1; done

Fail a CI job when an account is stopped:

airpost status --json | jq -e '[.engines[].accounts[] | select(.state != "running")] | length == 0'

Export this week’s events as a TSV:

airpost calendar list --json \
  | jq -r '.occurrences[] | [(.start // .startDate), .title, .eventId] | @tsv'

List the links clicked most this month:

airpost tracking links --since 30d --json | jq -r '.links[] | "\(.clickCount)\t\(.url)"'

Install a service plugin only if it’s exactly what you reviewed:

plan=$(airpost service install my-plugin --dry-run --json)
echo "$plan" | jq '{bin, sha256, unit: .unit.name}'
airpost service install my-plugin \
  --expect-sha256 "$(echo "$plan" | jq -r .sha256)" \
  --expect-plan "$(echo "$plan" | jq -r .planSha256)"

Call an engine method that has no command yet:

airpost rpc engine.status | jq .

Tips

  • Use ids, not subjects, between steps. Every list prints them, and they stay stable while a subject can match several threads.
  • Pass --dry-run to thread actions in scripts first and check the count, as in the archive example above.
  • Use --wait on sends and reprocess runs when the script’s next step depends on the server having the change; without it, commands return once the engine has queued the work.
  • --json turns off prompts. Commands that would ask need --yes, so a script never hangs waiting for input.

Related: Command reference, CLI overview.