Skip to content

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.

  1. --format <FORMAT> — table (default) for humans, json|jsonl|csv|ids for machines. The generated CLI reference lists the exact values per command.
  2. --dry-run previews 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.
  3. --yes — skip confirmation prompts on commands that ask before mutating. Required when stdin is not a TTY.
  4. 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.

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:

Terminal window
mxr search "is:unread" --account work --format ids
mxr cat --search "from:alice@example.com" --account personal --first
mxr deliveries --account work --format json

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:

Terminal window
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.

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.

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:

Terminal window
mxr archive --search 'from:noreply@example.com' --all --dry-run --format json
mxr archive --search 'from:noreply@example.com' --all --yes --format json

The 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:

Terminal window
mxr archive --account work --search "from:noreply@example.com older_than:30d" --dry-run
mxr archive --account work --search "from:noreply@example.com older_than:30d" --yes
  • mxr (no args) — launches the TUI. There is no --format json for “the TUI.”
  • mxr daemon — is a long-running process; structured output is on mxr status / mxr events / mxr logs.
  • mxr compose / mxr reply / mxr reply-all / mxr forward — open $EDITOR by 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 --demo is legacy; use mxr demo for an isolated fake-provider profile.
  • mxr accounts add — interactive wizard by default, but goes non-interactive when you pass enough flags AND set MXR_IMAP_PASSWORD / MXR_SMTP_PASSWORD / MXR_GMAIL_CLIENT_SECRET env vars.

For agents driving mutations, follow this pattern:

1. SEARCH — mxr search '<query>' --format json
2. CONFIRM — surface the candidates to the user
3. DRY-RUN — mxr <verb> --search '<query>' --dry-run
4. APPROVE — user signs off on the diff
5. MUTATE — mxr <verb> --search '<query>' --yes
6. RECORD — capture the printed mutation_id; offer mxr undo within ~60s
7. VERIFY — mxr history --category mutation --limit 1 --format json

Use 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:

Terminal window
mxr search 'from:noreply@example.com older_than:30d' --account work --format json
mxr archive --search 'from:noreply@example.com older_than:30d' --account work --dry-run
mxr archive --search 'from:noreply@example.com older_than:30d' --account work --yes
  • read-archive / trash / spam / star / unstar / read / unread / label / unlabel / move / snooze / unsnooze are 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_workspace JSON and operation ID. Keep that exact workspace JSON for mxr 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. An unknown outcome may have been accepted, so query it and do not resend. A not_accepted outcome means that operation was not accepted; review again and use a fresh operation ID for a new attempt.
  • mxr unsubscribe may hit a provider URL once; re-running on an already-unsubscribed message is harmless but emits no useful new state.
  • mxr undo MUTATION_ID works 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 with mxr undo. A plain absent mutation_id (no undo_unavailable) just means nothing was changed that undo could reverse (a dry run, or every message skipped).
  • Archive operation results always include mutation_id; run mxr undo only when that result also has undo_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.

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.