Airpost
The airpost command

Command reference

Every airpost subcommand, argument and flag.

This page lists every airpost command by group: what it does, its synopsis, its flags, examples with the output you should expect, and the shape of its --json document. Sample output uses made-up ids and addresses; the layout and wording come from the binary.

Every command also takes the global flags: --config-dir, -a/--account, --json, -h and -V. airpost <command> --help prints the same information from the binary you have.

Times written WHEN take 30m, 2h, 3d, 1w, tomorrow (9:00), tomorrow 14:30, a date (9:00 that day), or an ISO 8601 date and time (2026-11-02T14:30, local unless it has an offset).

Status and sync

status

The running engines and the state of their accounts, plus the installed services (engine, gateway, mcp-http). Exits 3 when no engine is running, but still prints the services.

airpost status [-a ACCOUNT]
$ airpost status
ACCOUNT            ID        STATE    SERVER  PID    UPTIME  ENGINE
you@gmail.com      54500b8c  running  ok      51838  2h 14m  0.1.0
you@fastmail.com   9e01a7d2  running  offline 51838  2h 14m  0.1.0

SERVICE   STATE          PID    URL                     BINARY
engine    running        51838  -                       /Applications/Airpost.app/Contents/MacOS/airpost-engine
gateway   not installed  -      -                       -
mcp-http  on demand      -      http://127.0.0.1:...    /Users/you/.local/bin/airpost-mcp

STATE is starting, running, stopped or removed; a stopped account shows the error key that stopped it (stopped: ErrorAuthentication) in red. SERVER is offline while a running account can’t reach its server.

Related: accounts, logs, The engine.

accounts

The accounts the running engines hold: id, email, state, the engine’s pid and socket.

$ airpost accounts
EMAIL             ID        STATE    PID
you@gmail.com     54500b8c  running  51838
you@fastmail.com  9e01a7d2  running  51838

sync

Start a sync pass now, on every account or the one --account names. Stopped accounts are skipped with a note. It returns once the pass has started; it doesn’t wait for it to end.

$ airpost sync -a you@example.com
Syncing you@example.com

--json: {"accounts": ["<account id>", ...]}, the accounts it woke.

watch

Print deltas and new mail as the engines send them, until interrupted. With --json it streams NDJSON; see JSON and scripting.

FlagDescription
-c, --class <CLASS>Only these model classes (Thread, Message, Folder, Task, …). New mail is printed either way.
--new-mailOnly new mail: one line per message that lands unread in the inbox.

Each line starts with the local time and the account. A delta line has the change type, the model class, how many models changed and a summary of the first:

$ airpost watch --new-mail
14:02:51  you@gmail.com  new mail 8c1d2e4f  thread 3a9f01b2
$ airpost watch -c Thread
14:03:10  you@gmail.com  persist Thread 1  Lunch on Thursday?

It runs until you press Ctrl-C. If an engine goes away the watch exits 1, since the stream would otherwise miss that account’s changes.

logs

Print an account’s engine log, or a service’s. Needs no engine.

airpost logs [ACCOUNT|SERVICE]
Argument / flagDescription
ACCOUNT|SERVICEAccount id or email, or engine, gateway or mcp-http. Defaults to --account, else the only account with a log.
-f, --followKeep printing lines as they are written, across log rotation.
-n, --lines <LINES>How many of the last lines to print first. Default 20.
airpost logs you@gmail.com -n 100
airpost logs engine -f

With --json each line is {"line": "..."}. See Background services for where each log lives.

Accounts

account

Add, change, reorder, resync, sign in again to and remove accounts of the serve engine.

account add

airpost account add <EMAIL> [flags]

IMAP accounts (the default) get the servers Airpost finds for the address, changed by the flags below, and a password: asked for on a terminal, or one line on stdin with --password-stdin. Gmail, Office 365 and Outlook accounts sign in in the browser (on a server, with --paste). The engine tests the account before it keeps it.

FlagDescription
--provider <PROVIDER>imap, gmail, office365, outlook, or a preset the servers come from (yahoo, icloud, fastmail, …). Default imap.
--name <NAME>Your name, as recipients see it.
--imap-host <HOST>IMAP server.
--imap-port <PORT>IMAP port.
--imap-security <tls|starttls>Airpost never sends a password unencrypted.
--imap-username <USER>IMAP username.
--smtp-host <HOST>SMTP server.
--smtp-port <PORT>SMTP port.
--smtp-security <tls|starttls>SMTP security.
--smtp-username <USER>SMTP username.
--password-stdinRead the password (IMAP and SMTP) from the first line of stdin.
--shared-mailbox <EMAIL>Office 365: open this shared mailbox with your own sign-in.
--no-browserPrint the sign-in address instead of opening the browser.
--pasteFor a server without a browser: print the sign-in address, then read the address the browser ends on (http://127.0.0.1:<port>/?code=...) from stdin instead of listening for it.
--port <PORT>The port on 127.0.0.1 the browser’s sign-in comes back to. Default 12141.
--timeout <TIMEOUT>Seconds to wait for the sign-in. Default 300.
printf '%s\n' "$PASSWORD" | airpost account add me@fastmail.com --provider fastmail --password-stdin
airpost account add me@gmail.com --provider gmail --paste

Related: account reauth, status.

account remove

Stop an account and remove it from the engine with its stored credentials (and a Google grant). The desktop window keeps listing it until it is removed there too.

Argument / flagDescription
ID|EMAILThe account.
--delete-dataAlso delete its mail cache. Without it the cache stays for an account added again.
-y, --yesDon’t ask first. Needed without a terminal, and with --json.

account update

Change how an account shows: its name, aliases and the alias new mail starts from.

Argument / flagDescription
ID|EMAILThe account.
--name <NAME>Your name, as recipients see it.
--alias <ALIAS>Add an alias to send from: Name <address>, an address, or a name. Repeatable.
--remove-alias <ALIAS>Remove an alias, by its text or address. Repeatable.
--default-alias <ALIAS|none>The alias new mail starts from; none for the account’s own address.

account reorder

airpost account reorder <ID|EMAIL>...

Put accounts in this order in the engine’s list. Accounts not named keep their order after these. The desktop window keeps its own order.

account resync

Delete an account’s mail cache and download its mail again, as Preferences > Accounts > Rebuild this account does.

Argument / flagDescription
ID|EMAILThe account.
-y, --yesDon’t ask first. Needed without a terminal, and with --json.

account reauth

Sign in to an account again: the browser for Gmail, Office 365 and Outlook, a new password for the others.

Argument / flagDescription
ID|EMAILThe account.
--password-stdinRead the new password from the first line of stdin.
--no-browserPrint the sign-in address instead of opening the browser.
--pasteRead the address the browser ends on from stdin.
--port <PORT>Callback port on 127.0.0.1. Default 12141.
--timeout <TIMEOUT>Seconds to wait for the sign-in. Default 300.

Reading mail

folders, labels

Folders (or labels) with unread and total thread counts.

airpost folders
airpost labels -a you@gmail.com

threads

Threads, newest first.

FlagDescription
--folder <FOLDER>A folder, by path or id.
--label <LABEL>A label, by path or id.
--role <ROLE>A role: inbox, sent, drafts, trash, spam, archive, all, important, …
-n, --limit <LIMIT>How many threads (default 50; with --all, the page size).
--allPage through every thread.
--before <CURSOR>Continue after a page: the next of threads --json (one account only).
$ airpost threads --role inbox -n 3 -a you@gmail.com
DATE    FROM                SUBJECT                        ID
09:41   Alice Chen          * Q4 planning notes            3a9f01b2
Nov 14  Bob Smith           Re: Lunch on Thursday?         77d0c3e9
Nov 12  GitHub              [airpost] CI failed on main    c24e8a10

Dates are the time for today, Mon DD for this year and YYYY-MM-DD before. A * marks a starred thread; unread threads are bold on a terminal. With several accounts there is an ACCOUNT column first.

Page through one account by hand:

next=$(airpost threads -a you@gmail.com --role all --json | jq -r .next)
airpost threads -a you@gmail.com --role all --before "$next"
airpost search <QUERY>...

Threads matching a query in the search bar’s grammar, newest first. Quote the whole query so the shell keeps its quotes and parentheses. There is no label:, cc:, -term or larger:; use in:<label> and NOT. See Search for the grammar.

FlagDescription
-n, --limit <LIMIT>How many threads (default 50).
airpost search 'from:alice "project alpha" after:2w'
airpost search 'is:unread in:inbox has:attachment' -n 20
airpost search '(from:bob OR from:carol) subject:invoice before:2026-10-01'

Output is the same table as threads. --json prints {"threads": [...]} with the same thread models.

Related: threads, show, and every thread action through --query.

show

airpost show <ID>

Given a thread id, the thread and its messages without bodies. Given a message id, the message and its attachments.

FlagDescription
--bodyWith a message id: include the body, downloading it first if needed.

With a thread id:

$ airpost show 77d0c3e9
Subject: Re: Lunch on Thursday?
With:    Bob Smith <bob@example.com>, you@gmail.com
In:      INBOX
Thread:  77d0c3e9

DATE    FROM        SNIPPET                                MESSAGE ID
Nov 13  Bob Smith   Are you free Thursday around noon?     5be1f0aa
Nov 14  You         Thursday works. The usual place?       e93c44d1
Nov 14  Bob Smith   Perfect, see you there.                0f7a2c58

With a message id and --body:

$ airpost show 0f7a2c58 --body
Subject: Re: Lunch on Thursday?
From:    Bob Smith <bob@example.com>
To:      you@gmail.com
Date:    2026-11-14 10:22 CET
Folders: INBOX
Flags:   unread
Files:   menu.pdf (84 KB, id 2d6e9b03)
Thread:  77d0c3e9
Id:      0f7a2c58

Perfect, see you there.

Without --body the last part is the snippet, followed by (snippet; --body shows the whole message). A Warning: line appears when the engine flagged the message (for example a sender that doesn’t match its domain).

attachment

SubcommandDescription
attachment get <FILE_ID>Save one attachment, downloading it if needed, and print its path. airpost show <message-id> lists file ids.
attachment save <MESSAGE_ID>Save every attachment of a message into a directory and print their paths.
FlagApplies toDescription
-o, --output <PATH>getWhere to write it (default: its name in the current directory); - for stdout.
--dir <DIR>saveThe directory (default: the current one); made if missing.
--forcebothReplace files that exist.
airpost attachment get 2d6e9b03 -o ~/Downloads/menu.pdf
airpost attachment get 2d6e9b03 -o - | pdftotext - -
airpost attachment save 0f7a2c58 --dir ./attachments

--json for get: {"accountId", "fileId", "filename", "contentType", "size", "path"}. For save: {"accountId", "messageId", "files": [...]}, one such object per file.

export

Save a message as an .eml file, or a folder as an mbox file (mboxrd), from the server’s copy.

airpost export <message-id> -o msg.eml
airpost export --mbox --folder INBOX -a me@example.com -o inbox.mbox
Argument / flagDescription
MESSAGE_IDThe message (airpost show <thread-id> lists them).
--mboxExport the folder --folder of the account as one mbox file.
--folder <FOLDER>With --mbox: the folder, by path, id or role.
-o, --output <FILE>Required. The file to write.
--forceReplace the file if it exists.
--timeout <SECS>Give up after this many seconds (default 120 for a message, none for a folder).

It prints the path written (and, for a folder, the message count: inbox.mbox (1243 messages)).

--json: for a message {"accountId", "messageId", "path", "size", "taskId"}; for --mbox {"accountId", "folder", "folderId", "path", "messages", "taskId"}.

Acting on threads

archive, trash, move, mark-read, mark-unread, star, unstar, spam, not-spam, label add and label remove all take thread ids from search or threads, in any account, or --query to act on every thread a search finds.

CommandWhat it does
archive [THREAD_ID]...Archive: Gmail takes threads out of the inbox, other accounts move them to Archive (or All Mail).
trash [THREAD_ID]...Move to the trash.
move <FOLDER> [THREAD_ID]...Move to a folder, by path, id or role. On Gmail the target can be a label: the threads’ labels are replaced by it.
mark-read, mark-unreadMark read or unread.
star, unstarStar or unstar.
spamMove to Spam.
not-spamMove out of Spam: to the inbox, or All Mail on Gmail. Only the copies in Spam move.
label add <LABEL> [THREAD_ID]...Add an existing label (Gmail).
label remove <LABEL> [THREAD_ID]...Take a label off.

Shared flags:

FlagDescription
-q, --query <QUERY>Every thread matching this search, instead of ids.
-n, --limit <LIMIT>With --query: at most this many threads, newest first. Without it, a query matching more than 500 threads is refused.
--dry-runList the threads it takes and check the folder or label; change nothing.
--waitWait until the change has reached the server; exit 1 if it fails.
--timeout <SECS>With --wait, give up after this many seconds.

Threads already as asked are left alone. The change shows in Airpost at once and reaches the server in the background. airpost undo takes it back.

$ airpost archive --query 'from:newsletter@example.com before:30d' --dry-run
Would archive 12 threads:
DATE    FROM             SUBJECT                      ID
Oct 10  Example Weekly   This week at Example         91be2c07
...

$ airpost archive --query 'from:newsletter@example.com before:30d' --wait
Archived 12 threads; task 6f2a91c0
Done: the server has the changes.

$ airpost star 3a9f01b2 77d0c3e9
Starred 1 thread (1 thread already starred); task b10e4d77

$ airpost move Receipts c24e8a10
Moved 1 thread to Receipts; task 0c9d5e12

With several accounts each account gets its own line (you@gmail.com: Archived 3 threads), then Queued tasks ....

Related: undo, search, task wait.

snooze, unsnooze

airpost snooze --until <WHEN> <THREAD_ID>...
airpost unsnooze <THREAD_ID>...

snooze moves threads to Snoozed until a time. unsnooze ends a snooze now and puts the threads back in the inbox.

$ airpost snooze --until 'tomorrow 8:00' 3a9f01b2
Snoozed 1 thread until 2026-11-17 08:00 CET

--json: {"accounts": [{"accountId", "threadIds", "taskIds", "undo"}], "until"}; until (Unix seconds) only for snooze.

remind

airpost remind <THREAD_ID|MESSAGE_ID|DRAFT_ID> --in <WHEN>

Bring a thread back to the top of the inbox if no one has replied by a time. Given a draft, the reminder goes with it when it is sent.

FlagDescription
--in <WHEN>When.
--clearRemove the reminder.

undo, redo

undo takes back airpost’s last change to threads (archive, trash, move, labels, read, star, spam, snooze), from the engine’s undo log. redo makes it again.

Argument / flagApplies toDescription
TOKENbothThe change, by the token airpost undo --list shows (or a command’s undo field in --json).
--anybothThe latest change of any client (Airpost, an agent, a script), not only airpost’s.
--waitbothWait until the change has reached the server; exit 1 if it fails.
--timeout <SECS>bothWith --wait, give up after this many seconds.
--listundoShow the log instead, newest first, with tokens.
--mineundoWith --list, airpost’s own changes only.
-n, --limit <LIMIT>undoWith --list, at most this many.
$ airpost undo --list -n 3
WHEN    CLIENT           CHANGE               STATE          TOKEN
14:10   airpost-cli      Archived 12 threads  done           u-81f2
14:02   airpost-mcp      Moved 1 thread       done           u-80aa
Nov 14  airpost-desktop  Marked 3 threads read undone (redo)  u-7c19

$ airpost undo
Undid: Archived 12 threads (airpost-cli)

Undoing a send that has already gone prints Too late: the message was already sent and exits 1.

unsubscribe

airpost unsubscribe <MESSAGE_ID> [--method one-click|mailto|web]

Unsubscribe from the mailing list a message came from. --method restricts it to one way: one-click asks the list’s server directly (Unsubscribed (one-click).), mailto sends the unsubscribe message, and web prints the page to open (This list unsubscribes on the web; open ...).

--json: {"method", "ok", "url", "error", "taskId"}. ok is false with error when it failed (exit 1); taskId is the send task for mailto.

Folders and labels

label create, rename, delete

SubcommandDescription
label create <NAME>Create a label on the account (--account, or the only one) and wait until the server has it. / nests it: Work/Clients.
label rename <LABEL> <NEW_NAME>Rename. The new name is the whole name, / between levels.
label delete <LABEL>Delete. Its mail stays, without the label.

folder

For accounts other than Gmail.

SubcommandDescription
folder create <NAME>Create a folder and wait until the server has it. / nests it: Projects/2026.
folder rename <FOLDER> <NEW_NAME>Rename. The new name is the whole name.
folder delete <FOLDER>Delete. The server deletes the mail in it too, so a folder holding threads is refused without --force.
folder empty <trash|spam|FOLDER>Delete every message in it for good. Asks first. trash and spam empty them in every account without --account.

Flags for create, rename, delete (and label create, rename, delete):

FlagDescription
--no-waitQueue the change and return without waiting for the server.
--timeout <SECS>Give up waiting after this many seconds. Default 60.
--forcefolder delete only: delete it even though it holds threads.
$ airpost label create Work/Clients -a you@gmail.com
Created label Work/Clients (id 1f8e0b6a)
$ airpost folder create Projects/2026 -a you@fastmail.com --no-wait
Queued: created folder projects/2026; task 4e7b19a3 (`airpost task wait 4e7b19a3`)

--json with --no-wait: {"accountId", "taskId"}. When it waits: {"accountId", "taskId", "status"} plus label or folder with the created model on create.

Flags for folder empty:

FlagDescription
--dry-runShow what would be deleted and delete nothing.
-y, --yesDon’t ask first. Needed without a terminal, and with --json.
--waitWait until the server has deleted them; exit 1 if it fails.
--timeout <SECS>With --wait, give up after this many seconds.

folder empty --dry-run --json: {"dryRun": true, "accounts": [{"accountId", "email", "threads", "folder": {"id", "path", "role"}}]}. Without --dry-run each account also has taskId.

Drafts and sending

A draft is saved to the account and shows in Airpost; nothing goes out until draft send. Write it (new, reply, reply-all, forward), change it (edit), check it (validate), then send it now, later (--at) or with an undo window (--undo). Drafts are named by the id from draft list (or the id these commands print) or by Message-ID.

draft new, reply, reply-all, forward

airpost draft new --to bob@example.com --subject "Lunch" --body "Thursday?"
airpost draft reply <MESSAGE_ID|THREAD_ID> --body-file reply.txt
airpost draft forward <MESSAGE_ID|THREAD_ID> --to carol@example.com

new writes from --account (default: the default sending account). reply, reply-all and forward take a message id, or a thread id for its newest message that isn’t a draft.

FlagDescription
--to <ADDRESSES>Recipients, replacing the draft’s: addresses or Name <address>, comma-separated or repeated.
--cc <ADDRESSES>Cc recipients, as --to.
--bcc <ADDRESSES>Bcc recipients, as --to.
--subject <SUBJECT>The subject, replacing the draft’s.
--body <BODY>The text, written above the signature and quoted text. Plain text unless --html.
--body-file <FILE|->Read the text from a file, or stdin with -.
--htmlThe text is HTML, and a new draft an HTML one.
--plainA plain-text draft. Without --html or --plain the draft follows the composer’s setting (core.composing.html).
--attach <PATH>Attach a file; repeatable. A file the draft already has isn’t attached again.
--template <NAME>Write the text from a template, as the composer’s template picker does.
--remind-in <WHEN>Remind you if no one replies by then.
--track-opensTrack opens. Needs an Airpost server that offers tracking, and an HTML draft.
--track-linksTrack link clicks. Same requirements.
--prefer-existingreply, reply-all: edit the draft already answering the message, if there is one. The default.
--no-prefer-existingreply, reply-all: always start a new draft.
$ airpost draft reply 77d0c3e9 --body "Sounds good, see you then."
Saved draft e2a4c771 in thread 77d0c3e9 to Bob Smith <bob@example.com>: Re: Lunch on Thursday?

When reply revises a draft that already answers the message, the line starts Updated instead of Saved. Attached: ... and Reminder: ... lines follow when they apply.

draft edit

airpost draft edit <DRAFT_ID|MESSAGE_ID> [flags]

Change a draft in place. Takes --to, --cc, --bcc, --subject, --body, --body-file, --html, --attach, --remind-in, --track-opens and --track-links as above, plus:

FlagDescription
--detach <NAME|ID>Remove an attachment, by file name or id; repeatable.

Refused while the draft is being sent or scheduled to send.

draft validate

airpost draft validate <DRAFT_ID|MESSAGE_ID>

Run the checks send runs, without sending. Errors (no recipients, a bad address) exit 1; warnings (no subject, a forgotten attachment) don’t.

$ airpost draft validate e2a4c771
airpost: warning: ...
Draft e2a4c771 can be sent

draft send

airpost draft send <DRAFT_ID|MESSAGE_ID> [flags]

Send a draft now, later, or after an undo window. The validate checks run first: errors stop it, warnings are printed. Once it goes it can’t be called back.

FlagDescription
--archiveArchive the thread once it is sent.
--waitWait until the mail has gone; exit 1 if the send fails.
--timeout <SECS>With --wait, give up after this many seconds.
--at <WHEN>Send later, at this time. The engine sends it then, with or without Airpost open.
--undo <SECS>Hold the send this many seconds (at most 3600); draft cancel-send calls it back until then.
--remind-in <WHEN>Remind you if no one replies by then.
--track-opens, --track-linksAs above.
$ airpost draft send e2a4c771
Sending draft <message-id> (task 9a0f33c1; `airpost task wait 9a0f33c1` waits for it)

$ airpost draft send e2a4c771 --at 'tomorrow 9:00'
Draft e2a4c771 sends 2026-11-17 09:00 CET (`airpost draft cancel-send e2a4c771` stops it until then)

$ airpost draft send e2a4c771 --wait
SendDraftTask 9a0f33c1 complete

Related: draft scheduled, remind, tracking, undo (undoes a send still in its --undo window).

Other draft commands

SubcommandDescription
draft cancel-send <DRAFT_ID|MESSAGE_ID>Stop a pending send (scheduled with --at or waiting out --undo). The draft stays.
draft delete <DRAFT_ID|MESSAGE_ID>Delete a draft. A pending send is cancelled with it; one already going out can’t be.
draft scheduledDrafts waiting to send, soonest first, and scheduled sends that failed.
draft list [-n LIMIT]Unsent drafts, newest first. -n is per account, default 50.

draft list columns are DATE, TO, SUBJECT, FILES, THREAD, ID; draft scheduled columns are SEND AT, STATE, TO, SUBJECT, ID, where STATE is scheduled (--at), undo (waiting out --undo) or failed.

tracking

Opens and link clicks of sent mail that had tracking on.

CommandDescription
tracking <MESSAGE_ID>A sent message’s opens and clicks.
tracking listSent messages with tracking on, newest first.
tracking linksThe most clicked tracked links.
FlagApplies toDescription
--type <opens|links|either>listOnly messages tracking this. Default either.
--since <WHEN>list, linksOnly mail sent since then: 3h, 7d, 2w, or a date.
-n, --limit <LIMIT>list, linksHow many (default 50 messages, 10 links).

tracking list columns are DATE, TO, SUBJECT, OPENS, CLICKS, ID.

$ airpost tracking 7c41e0a2
Proposal for Q1 (2026-11-11 17:02 +01:00)
Opens: 2
  2026-11-12 09:14 +01:00 dana@example.com
  2026-11-12 13:40 +01:00 dana@example.com
Clicks: 1
  1 https://example.com/pricing
    2026-11-12 09:15 +01:00 dana@example.com

Without tracking data, tracking <MESSAGE_ID> exits 1 with message <id> wasn't sent with tracking on.

Templates, signatures and rules

template

Alias: templates. The composer’s templates (Preferences > Templates).

SubcommandDescription
template listName, subject, variables and the start of the text.
template show <NAME>Subject, variables and text (HTML in --json).
template save [NAME]Save a template from text, or from a draft. Names are letters, digits, spaces, - and _; a name in use gets a number unless --replace.
template delete <NAME>Delete a template.

template save flags:

FlagDescription
--subject <SUBJECT>The subject a new draft from the template gets.
--body <BODY>The text, plain unless --html; {{name}} becomes a variable.
--body-file <FILE|->Read the text from a file, or stdin with -.
--htmlThe text is HTML.
--from-draft <DRAFT_ID>Save this draft as the template (the text above the signature and quote, named after the subject).
--replaceWrite over the template of that name.
airpost template save 'Intro call' --subject 'Quick intro' \
  --body 'Hi {{name}}, would you have 20 minutes next week?'
airpost template show 'Intro call' --json | jq -r '.template.variables[]'

signature

Alias: signatures. The composer’s signatures (Preferences > Signatures).

SubcommandDescription
signature listId, name, the addresses that start with each, and the start of the text.
signature show <NAME|ID>The text (HTML in --json) and the addresses that use it.
signature set <NAME|ID>Save a signature: the one with that name or id, else a new one.
signature delete <NAME|ID>Delete; the addresses that used it start without one.
signature default <NAME|ID|none>The signature an address starts new mail and replies with: the account’s address, or the addresses --for names.
FlagApplies toDescription
--title <TITLE>setRename it.
--body <BODY>setThe text, plain unless --html.
--body-file <FILE|->setRead the text from a file, or stdin.
--htmlsetThe text is HTML.
--for <ADDRESS>defaultAn account’s own address or an alias’s. Repeatable.

Signatures live in the engine’s signatures setting, and the per-address choice in defaultSignatures, so the desktop and the CLI see the same ones.

airpost signature set Work --body-file ~/sig.html --html
airpost signature default Work --for you@work.example --for team@work.example
airpost signature default none --for you@home.example

rules

Alias: rule. Mail rules (Preferences > Mail Rules). The engine applies them to arriving mail, with or without Airpost open. A RULE is its id or name.

SubcommandDescription
rules listThe rules in the order they run.
rules show <RULE>Conditions and actions, and why the engine turned it off if it did.
rules addAdd a rule to the account (--account, or the only one), after the others.
rules update <RULE>Change name, conditions, actions or match.
rules remove <RULE>Delete. Alias: delete.
rules enable <RULE>Turn on, also one the engine turned off after an error.
rules disable <RULE>Turn off.
rules reprocessRun the rules that are on over the inbox, newest first, showing progress. Interrupting stops the run.

add and update flags:

FlagDescription
--name <NAME>The rule’s name.
--if <CONDITION>FIELD COMPARATOR VALUE. Repeatable; on update they replace the rule’s conditions.
--then <ACTION>An action. Repeatable; on update they replace the rule’s actions.
--match <all|any>Every condition must match, or one is enough.
--rule <JSON|->The rule (on update, the fields to change) as JSON, in the shape rules show --json prints, or - for stdin.
--disabledadd only: save it turned off.

Condition fields: from, to, cc, bcc, recipient, reply-to, attachment-name, subject, body. Comparators: contains, not-contains, begins-with, ends-with, equals, matches (a regular expression). Also has-attachment and starred, with true (the default) or false.

Actions: mark-read, star, trash, forward ADDRESS, move FOLDER; on Gmail also label LABEL, move LABEL (replacing the other labels), archive, important.

reprocess flags: --wait (also wait until the changes have reached the server; exit 1 if one fails) and --timeout <SECS> (give up, stopping the run).

airpost rules add --name Receipts --if 'from contains shop.example' --then 'move Receipts'

A rule is checked before it is saved: an unknown field, a bad expression or a missing folder is refused.

More examples:

airpost rules add -a you@gmail.com --name 'CI noise' --match any \
  --if 'from equals notifications@github.com' --if 'subject contains [ci]' \
  --then archive --then 'label CI'
airpost rules update 'CI noise' --then mark-read --then archive
airpost rules disable 'CI noise'
airpost rules reprocess -a you@gmail.com --wait

rules list columns are NAME, ACCOUNT, STATE, IF, THEN, ID. --json prints {"rules": [...]}; rules show --json prints one rule in the shape --rule accepts, so you can edit it and feed it back:

airpost rules show 'CI noise' --json > rule.json
# edit rule.json
airpost rules update 'CI noise' --rule - < rule.json

For example, airpost rules add --name Receipts --if 'from contains shop.example' --then 'move Receipts' --json prints a rule like:

{
  "rule": {
    "id": "local-6f1c02ab-9d4e",
    "accountId": "54500b8c",
    "name": "Receipts",
    "conditionMode": "all",
    "conditions": [{"templateKey": "from", "comparatorKey": "contains", "value": "shop.example"}],
    "actions": [{"templateKey": "changeFolder", "value": "<folder id>", "valueName": "Receipts"}],
    "disabled": false
  }
}

Contacts and calendar

contacts

airpost contacts <QUERY>... [-n LIMIT]

Contacts whose name or address starts with the query’s words. Default limit 50.

contact

SubcommandDescription
contact get <CONTACT_ID>A contact’s details.
contact createA new contact in the account’s address book.
contact update <CONTACT_ID>Change a contact; the fields given replace the stored ones.
contact import <FILE>Add the vCards of a .vcf file (or - for stdin) as new contacts.
contact export <CONTACT_ID>...Print contacts as a .vcf file.

create and update flags: --patch <JSON> (fields in the shape contact get --json prints under data), --name <NAME> ("Given Family"), --email, --phone, --company, --title, --notes.

airpost contacts dana
airpost contact create --name 'Dana Ruiz' --email dana@example.com --company Acme
airpost contact import ~/Downloads/team.vcf
airpost contact export k_12 k_13 > two.vcf

contacts columns are NAME, EMAIL, REFS (how often the address appears in mail, which orders the list), plus ACCOUNT with several accounts. contact import prints Imported <n> contacts into <account>.

calendars

The calendars: id, account, name, and whether each is read-only.

calendar

SubcommandDescription
calendar syncStart a calendar pass now.
calendar listEvents between two times, every occurrence of a repeating one.
calendar createCreate an event; with guests it is organised by the account.
calendar update <EVENT_ID>Change or delete an event, one occurrence, or it from one occurrence on.
calendar rsvp <EVENT_ID> <accepted|tentative|declined>Answer an invitation and tell the organizer by mail, or propose another time.

calendar list:

FlagDescription
--from <WHEN>From; now by default.
--to <WHEN>To; a week after --from by default.
--calendar <ID>Only these calendars.

calendar create:

FlagDescription
--calendar <ID>Required. The calendar’s id (airpost calendars). Give --account when there are several accounts.
--title <TITLE>Required.
--start <WHEN>Required.
--end <WHEN>An hour after --start by default (a day for --all-day).
--all-dayAn all-day event.
--location <LOCATION>
--description <DESCRIPTION>
--guest <EMAIL>Guests’ addresses.
--repeat <RULE>An RRULE, e.g. FREQ=WEEKLY;BYDAY=MO.

calendar update:

FlagDescription
--scope <this|following|all>Which occurrences of a repeating event. Default all.
--occurrence <WHEN>The occurrence this or following starts from, by its start.
--start, --end <WHEN>New times.
--title, --location, --descriptionNew values.
--deleteDelete instead.

calendar rsvp: --comment <COMMENT>, and --propose-start <WHEN> with --propose-end <WHEN> for a counter-proposal.

WHEN is a date and time such as 2026-11-02T14:30, read in your local time zone.

airpost calendars
airpost calendar list --from 2026-11-17 --to 2026-11-21
airpost calendar create --calendar c_work --title 'Design review' \
  --start 2026-11-19T14:00 --guest lee@example.com
airpost calendar update e_77 --start 2026-11-19T15:00 --end 2026-11-19T16:00
airpost calendar rsvp e_77 accepted --comment 'See you there'

calendar list columns are WHEN, TITLE, EVENT; with nothing in range it prints No events. create and update print one line per write, Queued: <kind> <eventId>, or Nothing to change. rsvp prints Answered accepted as you@work.example; the organizer is told by mail, or Proposed a new time to the organizer.

AI

Through the provider set up in Preferences > AI. See AI.

SubcommandDescription
ai summarize <THREAD_ID> [--refresh]Summarize a thread, printing the text as the model writes it. --refresh asks the model again instead of printing the cached summary.
ai triage [THREAD_ID]... [--since AGE]Triage inbox threads (needs-reply, important, …) and wait until done. --since is 7d, 2w, or days (default 7d).
ai usage [--days DAYS]Tokens used per day, provider and feature. Default 30 days.
airpost ai summarize 3a9f01b2
airpost ai triage --since 2w
airpost ai usage --days 7 --json | jq 'map(.inputTokens + .outputTokens) | add'

ai triage prints <account>: triaged <done> of <n> threads per account, and exits 1 if a run stops early (the account stopped, the job was cancelled or triage was turned off).

Settings and tasks

settings

The settings the engine keeps for every client (undo send, the default sending account, signatures, …).

SubcommandDescription
settings get [KEY]...The stored values, of these keys or every key. A key without a value is left out.
settings set <KEY> <VALUE>Store a value: JSON (15000, true, {...}), else the text as a string. null clears the key.

settings get --json prints {"values": {"<key>": <value>}}.

task

Alias: tasks. The engine’s task queue.

SubcommandDescription
task listPending tasks first, oldest queued first, then finished ones, newest first.
task queue <JSON|->Queue a task: its JSON, or - for stdin. id, aid and status are filled in when missing.
task cancel <ID>Ask the engine to cancel a task.
task wait <ID>Wait until a task completes; exit 1 if it fails or doesn’t exist.
$ airpost task list -n 3
CLASS                 STATUS    ERROR  ID
SendDraftTask         remote           9a0f33c1
ChangeFolderTask      complete         6f2a91c0
SyncbackCategoryTask  complete         4e7b19a3

$ airpost task wait 9a0f33c1
SendDraftTask 9a0f33c1 complete

task list --json is a bare array of task models. task queue prints Queued <class> <id> (<status>), and with --json the task after its local phase. task cancel --json prints {"accountId", "taskId"}. task wait --json and task queue --wait --json print the finished task.

FlagApplies toDescription
--status <STATUS>listOnly these statuses: local, remote, complete, cancelled.
--class <CLASS>listOnly this class, e.g. SendDraftTask.
--header-message-id <ID>listOnly tasks naming this draft.
-n, --limit <LIMIT>listTasks per account (default 50).
--waitqueueWait until the task completes; exit 1 if it fails.
--timeout <SECS>queue, waitGive up after this many seconds.

rpc

airpost rpc <METHOD> [PARAMS]

Send one raw JSON-RPC request to the engine and print its result. PARAMS is the params object; accountId picks the engine when several run.

airpost rpc engine.status
airpost rpc threads.get '{"accountId": "54500b8c", "id": "3a9f01b2"}'

It prints the result as indented JSON, or compact with --json. Treat it as a debugging tool: methods change between versions, and a raw call can write to your account.

Services

These install and manage launchd or systemd user units. They’re covered in Background services.

CommandDescription
engine install|uninstall|start|stop|restartThe engine, started at login.
gateway install|uninstall|start|stop|restart|pairThe web client’s server, started on the first connection.
mcp-http install|uninstall|start|stop|restartairpost-mcp http, started on the first connection.
service install|uninstall|listService plugins’ background programs.
uninstallRemove every unit airpost installed for the profile, and the PATH link.

skill

airpost skill install|uninstall|print installs the agent skill for airpost into Claude Code and Codex. See Agent skill.