Automation contract
mxr is built to be scripted, but commands differ in which automation primitives they support. This page describes the common patterns; check the command reference before composing a pipeline or agent action.
When in doubt, the auto-generated CLI reference is the source of truth. The tables below summarise the patterns.
The four primitives
Section titled “The four primitives”--format <FORMAT>—table(default) for humans,json|jsonl|csv|idsfor machines. The generated CLI reference lists the exact values per command.--dry-runpreviews a command’s supported changes without mutating provider state. Many core mail mutations and selected lifecycle commands support it; check the generated CLI reference for each command.--yes— skip confirmation prompts on commands that ask before mutating. Required when stdin is not a TTY.- stdin IDs — pass message IDs on stdin, one per line. Equivalent to listing them as positional args. Available on most mutations; not all.
Most mail-facing commands also accept --account <selector>. Use it
to restrict a read, search, list, draft, delivery, invite, saved-search
run, or mutation to one enabled account. Selectors accept account key,
email address, account id, or an unambiguous display name.
When omitted, commands keep their normal behavior. Search, list, read, and batch mutation surfaces operate across all enabled accounts by default. Unknown or ambiguous selectors fail before mxr sends the daemon request, and direct-ID commands validate that the selected account owns the target before acting.
MCP profile gates apply to requests identified as MCP or agent IPC origins.
Ordinary CLI requests use CLI origin, including when a shell-capable agent
invokes mxr; the profile does not restrict that process’s other shell
commands. See For agents for the client and OS boundary.
Reads (commands that return data)
Section titled “Reads (commands that return data)”These are the common automation-oriented read surfaces. Exact formats live in the generated CLI reference. JSON shapes per command live in JSON output schemas.
| Command | Returns | Pipeable formats |
|---|---|---|
mxr search |
envelopes (matching messages) | json, jsonl, csv, ids, table |
mxr count |
scalar count | json, jsonl, table/text |
mxr cat |
full message body | json, jsonl, table (and the --view modes for body rendering) |
mxr thread |
thread + messages | json, jsonl, table |
mxr thread-preview |
up to 100 threads’ subject, latest sender, date, snippet, counts, attachments (no bodies) | json, jsonl, csv, ids, table |
mxr headers |
RFC 822 headers | json, jsonl, table |
mxr labels |
labels with counts | json, jsonl, csv, ids, table |
mxr saved list / mxr saved run <name> |
saved searches / matches | json, jsonl, csv, ids, table |
mxr drafts list |
drafts | json, jsonl, csv, ids, table |
mxr replies list |
reply-later queue | json, jsonl, table |
mxr snippets list |
snippets | json, jsonl, table |
mxr storage / mxr stale / mxr response-time / mxr contacts / mxr subscriptions / mxr wrapped |
analytics summaries | json, jsonl, csv, table |
mxr status |
daemon health | json, jsonl, table |
mxr serve status / mxr serve pair list / mxr serve clients |
local host pairing authority and registrations | json (default), jsonl |
mxr connect --status |
selected target and pending deregistration | json (default), jsonl |
mxr sync --status |
sync state per account | json, jsonl, table |
mxr events / mxr history / mxr logs |
streaming event/log records | json, jsonl, csv, table |
mxr notify |
unread summary | json, jsonl, text |
mxr accounts |
runtime account inventory | json, jsonl, csv, ids, table |
mxr config show |
resolved config | json, jsonl, csv, ids, table |
mxr config get |
one config value | text |
mxr attachments list |
attachments for a message | table/text |
mxr export |
thread export | markdown, json, mbox, llm |
Account-scoped reads:
mxr search "is:unread" --account work --format idsmxr cat --search "from:alice@example.com" --account personal --firstmxr deliveries --account work --format jsonCreating drafts from an external program
Section titled “Creating drafts from an external program”mxr compose is the supported interface for a program that wants mxr to create
a draft — including HTML drafts with inline images. It reports structured output
under --format json/jsonl, so callers read a draft id rather than scraping
a human string:
mxr compose --account notto --to person@example.com \ --subject "Product Digest" --html-file message.html \ --inline notto-logo=logo.png --draft --format json{ "action": "save_draft", "draft_id": "draft_abc123", "account_id": "acct_...", "subject": "Product Digest", "to": ["person@example.com"], "content_kind": "html", "inline_count": 1, "attachment_count": 0, "local_message_id": null}--draft cannot send: it conflicts with --yes in the parser. Sending stays a
separate reviewed mxr send DRAFT_ID call using the revision, exact
expected_workspace JSON and operation ID from its preview.
This CLI contract is the supported integration path for external tools such as
mxr-mailmerge. The daemon socket exists but is not a
public contract — prefer the CLI unless you have measured a reason not to.
Mutations (destructive or stateful)
Section titled “Mutations (destructive or stateful)”Core mail mutations accept either explicit message IDs as positional args, --search QUERY for batch ops, or piped IDs on stdin. Use the generated CLI reference for non-mail lifecycle commands.
| Command | Targets | --dry-run |
--search |
stdin IDs |
|---|---|---|---|---|
mxr archive |
message(s) | ✓ | ✓ | ✓ |
mxr read-archive |
message(s) | ✓ | ✓ | ✓ |
mxr trash |
message(s) | ✓ | ✓ | ✓ |
mxr spam |
message(s) | ✓ | ✓ | ✓ |
mxr star / mxr unstar |
message(s) | ✓ | ✓ | ✓ |
mxr read / mxr unread |
message(s) | ✓ | ✓ | ✓ |
mxr label NAME / mxr unlabel NAME |
message(s) | ✓ | ✓ | ✓ |
mxr move LABEL |
message(s) | ✓ | ✓ | ✓ |
mxr snooze |
message(s) | ✓ | ✓ | ✓ |
mxr unsnooze |
message(s) or --all |
✓ | — | ✓ |
mxr unsubscribe |
message(s) | ✓ | ✓ | ✓ |
mxr undo MUTATION_ID |
one mutation | ✓ | — | — |
mxr send DRAFT_ID |
a draft | ✓ (--at conflicts) |
— | — |
mxr unsend DRAFT_ID |
a scheduled send | — | — | — |
mxr drafts delete DRAFT_ID |
one local draft | ✓ | — | — |
mxr drafts push DRAFT_ID |
one local draft + provider capability | ✓ | — | — |
mxr rules dry-run |
a rule | n/a (always dry-run) | — | — |
mxr serve pair approve / mxr serve clients revoke |
one local pairing / registration | yes; preview by default, commit with --confirm |
— | — |
mxr connect HTTPS_ORIGIN / mxr connect --local |
this installation’s saved connection | yes; preview by default, commit with --confirm |
— | — |
--search acts on at most the newest 1,000 matches, found with a lexical
search whatever search.default_mode is, so a typo like --search '*' cannot
fan out across the whole mailbox. When more than 1,000 match, the dry run, the
confirmation prompt and (with --yes) stderr all say so before anything
changes, and JSON output gains capped: true
(schema).
Narrow the query to reach the rest, or, for archive, read-archive, label and unlabel, pass --all (below). Explicit and piped IDs have no cap. mxr unsubscribe <address> says the same per address.
Every match: --all
Section titled “Every match: --all”archive, read-archive, label and unlabel accept --all with --search
to act on every match instead of the newest 1,000. It conflicts with message
IDs and --async, and the daemon does the work: it resolves the search once,
counts it exactly, and runs it as one background job, so the command never
holds or sends a list of IDs. The loop is the same as for any batch:
mxr archive --search 'from:noreply@example.com' --all --dry-run --format jsonmxr archive --search 'from:noreply@example.com' --all --yes --format jsonThe dry run reports selected_messages, selected_threads, the per-account
counts, a sample of the 20 newest messages, capped: false and a
preview_token. --all --yes previews, starts one job over exactly those
messages, waits for it with progress on stderr, and prints it; mail that
arrives after the preview is left alone. --no-wait returns once the daemon has
accepted the job (follow it with mxr jobs JOB_ID), and
--preview-token TOKEN runs exactly what an earlier dry run counted. label --all and unlabel --all accept only labels you created in each account they reach: a system label such as INBOX, TRASH or SPAM (which move, trash or spam mail at the provider), a provider folder, an IMAP flag or a name that matches no label is refused. The dry run pins each name to that label, so a rename afterwards does not change which label the job edits, and a label deleted before the job starts refuses the start (“preview again”). Trashing and spamming are not available for --all yet. The exit
status is non-zero when the job ends failed, whatever it had done by then.
An --all job cannot be undone: it keeps no undo, so the dry run is the check,
and mxr undo JOB_ID on one refuses and says so. A daemon restart ends a
running job as failed (“interrupted”) with its persisted counts; running the
same search again finishes what is left. The shapes are in the
JSON output reference.
Account-scoped mutations use the same target set for preview and apply:
mxr archive --account work --search "from:noreply@example.com older_than:30d" --dry-runmxr archive --account work --search "from:noreply@example.com older_than:30d" --yesWhat’s not scriptable
Section titled “What’s not scriptable”mxr(no args) — launches the TUI. There is no--format jsonfor “the TUI.”mxr daemon— is a long-running process; structured output is onmxr status/mxr events/mxr logs.mxr compose/mxr reply/mxr reply-all/mxr forward— open$EDITORby default. For scripts, use--body,--body-stdin,--yes, and--dry-run, or use the HTTP bridge’s compose endpoints.mxr setup— interactive first-run account setup.mxr setup --demois legacy; usemxr demofor an isolated fake-provider profile.mxr accounts add— interactive wizard by default, but goes non-interactive when you pass enough flags AND setMXR_IMAP_PASSWORD/MXR_SMTP_PASSWORD/MXR_GMAIL_CLIENT_SECRETenv vars.
Safe agent loop
Section titled “Safe agent loop”For agents driving mutations, follow this pattern:
1. SEARCH — mxr search '<query>' --format json2. CONFIRM — surface the candidates to the user3. DRY-RUN — mxr <verb> --search '<query>' --dry-run4. APPROVE — user signs off on the diff5. MUTATE — mxr <verb> --search '<query>' --yes6. RECORD — capture the printed mutation_id; offer mxr undo within ~60s7. VERIFY — mxr history --category mutation --limit 1 --format jsonUse this as a review pattern, then check the command reference for the exact preview, input, and output support of the command you chose. The daemon does not provide every primitive for every action.
When the user names an account, keep that selector on every step:
mxr search 'from:noreply@example.com older_than:30d' --account work --format jsonmxr archive --search 'from:noreply@example.com older_than:30d' --account work --dry-runmxr archive --search 'from:noreply@example.com older_than:30d' --account work --yesIdempotency
Section titled “Idempotency”read-archive/trash/spam/star/unstar/read/unread/label/unlabel/move/snooze/unsnoozeare idempotent — re-running with the same target IDs leaves state unchanged after the first call.- For a mailbox Archive operation with a lost response, query its retained operation ID before acting again. State idempotence does not prove whether the provider received the earlier dispatch; see the recovery recipe.
- A saved-draft send is bound to its reviewed revision, original
expected_workspaceJSON and operation ID. Keep that exact workspace JSON formxr send-outcome, including after the draft has been removed; do not infer a new owner from the selected daemon. The daemon does not start another send for an existing operation. Anunknownoutcome may have been accepted, so query it and do not resend. Anot_acceptedoutcome means that operation was not accepted; review again and use a fresh operation ID for a new attempt. mxr unsubscribemay hit a provider URL once; re-running on an already-unsubscribed message is harmless but emits no useful new state.mxr undo MUTATION_IDworks within a 60-second window; after that it returns an error.- An undoable mutation normally returns a
mutation_id. If that field is absent and the result has"undo_unavailable": true, the mutation succeeded but its undo entry could not be recorded — it can’t be reversed withmxr undo. A plain absentmutation_id(noundo_unavailable) just means nothing was changed that undo could reverse (a dry run, or every message skipped). - Archive operation results always include
mutation_id; runmxr undoonly when that result also hasundo_available: true.
For a saved draft, preview first and retain both the reviewed revision and the
operation ID. The send command prints the ID and an outcome-query command to
stderr before submission. Query that ID after a lost response rather than
rerunning a one-shot command. compose, reply, reply-all, and forward
with --yes create and send a new draft on each invocation, so rerunning one
can create a second message even though saved-draft operations are protected.
See crash-safe drafts for the review and recovery
steps.
Failures a script can branch on
Section titled “Failures a script can branch on”A missing or incompatible daemon exits 3, and an auth failure exits 4; other errors exit 1. With JSON output, those two also write one {"error":{"kind":…}} line to stderr, so stdout stays results-only. See exit codes.
See also
Section titled “See also”- CLI reference — every command, every flag, auto-generated
- JSON output schemas — field names you can pipe into
jq - Recipes — copy-pasteable pipelines using these primitives
- For agents — patterns and safe defaults when an LLM is driving