Skip to content

JSON output schemas

mxr’s CLI JSON is the automation contract. Human table output can change; json, jsonl, csv, and ids are the surfaces to script.

The CLI does not always mirror daemon IPC structs. Some commands intentionally emit smaller records that are easier to pipe.

mxr search QUERY --format json returns one object with results, paging, and explain. It is not a bare array, so jq filters need to go through .results.

{
"results": [
{
"message_id": "019706f4-9b6e-7c31-8a3f-2a1c4de50b91",
"from": "Sarah Chen <sarah@example.com>",
"subject": "1:1 prep, Friday",
"date": "2026-04-30T15:42:11+00:00",
"read": false,
"starred": true,
"score": 1777563776.0
}
],
"paging": {
"limit": 50,
"offset": 0,
"total": 73,
"has_more": true,
"next_offset": 50
},
"explain": null
}
Field Type Notes
message_id string Pass to mxr cat, mxr reply, mutations, etc.
from string Display-ready sender, usually Name <email>. Missing display names leave a leading space before <email>.
subject string Empty subjects are possible.
date string RFC 3339 timestamp.
read bool Current local read state.
starred bool Current local starred state.
score number The ranking value the executed search produced, as a 32-bit float. Its meaning depends on how the search ran; see below.

The mode you request and the path the search falls back to together decide what score holds.

Request Execution score
--mode lexical --sort relevance lexical BM25 relevance
--mode lexical with the default date sort lexical message date in Unix seconds
--mode hybrid hybrid RRF fusion score
--mode semantic semantic dense score
--mode hybrid or --mode semantic lexical fallback BM25 relevance
any mode, query rejected by the structured parser Tantivy fallback matches the requested sort

Omitting --mode picks the request path from search.default_mode.

An f32 carries 24 mantissa bits, so present-day epoch seconds land on 128-second steps: the example message is 1777563731 and comes back as 1777563776.0. Read date when you need a stable value.

paging sits in the JSON envelope. --format jsonl and --format csv write the same object to stderr instead.

Field Type Notes
limit number The page size the CLI sent. Defaults to 50 when --limit is omitted.
offset number The --offset value. Defaults to 0.
total number Match count for the query, not the number of rows on this page.
has_more bool True when matches exist past this page.
next_offset number or null Offset to pass to --offset for the next page. Null when has_more is false.

results is [] when nothing matches, and total is then 0. A lexical request reports the full match count for the query. A hybrid or semantic request ranks a bounded candidate window, and its total can be the size of that pool rather than a full count. Use has_more and next_offset to page.

explain is null unless you pass --explain.

Terminal window
mxr search 'quarterly report' --mode hybrid --explain --format json

An illustrative explain for that command, on a config with semantic search switched off:

{
"explain": {
"requested_mode": "hybrid",
"executed_mode": "lexical",
"semantic_query": "quarterly report",
"lexical_window": 204,
"dense_window": null,
"lexical_candidates": 73,
"dense_candidates": 0,
"final_results": 50,
"rrf_k": null,
"notes": ["semantic search disabled in config; used lexical ranking"],
"results": [
{
"rank": 1,
"message_id": "019706f4-9b6e-7c31-8a3f-2a1c4de50b91",
"final_score": 12.4,
"lexical_rank": 1,
"lexical_score": 12.4,
"dense_rank": null,
"dense_score": null
}
]
}
}
Field Type Notes
requested_mode string lexical, hybrid, or semantic, as asked for by --mode.
executed_mode string What actually ran. It falls back to lexical when semantic retrieval is unavailable.
semantic_query string or null Semantic text extracted from the query. The lexical fallback paths set it too, so a value here does not prove a dense pass ran.
lexical_window number Candidate window for the lexical pass. Equal to --limit for a lexical request, wider for a hybrid or semantic one, including requests that fall back to lexical.
dense_window number or null Candidate window for the dense pass. Null when no dense pass ran.
lexical_candidates number Rows the lexical pass produced.
dense_candidates number Dense rows left after filtering. 0 when no dense pass ran.
final_results number Rows returned on this page, recounted after post-search filters such as disabled accounts.
rrf_k number or null Reciprocal rank fusion constant. Set only when hybrid fusion ran.
notes string[] Reasons for fallbacks and other diagnostics.
results[] object[] One entry per row on the page, with rank, message_id, final_score, and the nullable lexical_rank, lexical_score, dense_rank, dense_score. --format table and --format ids print only the first five; JSON carries all of them.

--format jsonl writes the same result records to stdout, one per line, and writes the paging and explain envelope to stderr as a single line. Capture stderr if you need to page.

Terminal window
mxr search 'from:sarah@example.com' --format jsonl 2>/dev/null | jq -r '.subject'
mxr search 'from:sarah@example.com' --format jsonl 2>paging.json >/dev/null && jq '.paging.next_offset' paging.json
{"message_id":"019706f4-9b6e-7c31-8a3f-2a1c4de50b91","from":"Sarah Chen <sarah@example.com>","subject":"1:1 prep, Friday","date":"2026-04-30T15:42:11+00:00","read":false,"starred":true,"score":1777563776.0}

The stderr line has the same shape in --format csv.

--group-by from|list|category runs an aggregation instead of a message search, so the payload is different. --format json returns one object:

{
"query": "invoice",
"group_by": "from",
"total": 12,
"groups": [
{
"key": "billing@example.com",
"label": "Example Billing <billing@example.com>",
"count": 8,
"unread": 2,
"oldest": 1704067200,
"newest": 1777564800
}
]
}

--format jsonl flattens each group onto its own line and repeats query and group_by on every line. key is the normalized grouping value and label is the display form. oldest and newest are Unix seconds and are typed as nullable. total counts matching messages, not groups, and --group-by category can file one message under several categories, so the group counts can add up to more than total.

Groups are sorted by count descending, then unread descending, then newest descending, then label. --limit truncates that sorted list. Aggregations have no paging and no explain, and --offset is not sent.

--mode applies to aggregations too, and it decides how much of the mailbox they see. A lexical aggregation groups every match, so total and the groups describe the same messages.

A hybrid or semantic aggregation runs the query twice. The first run decides how many top results the second run will group. The second run searches a candidate pool that can be wider, and total reports how many candidates it ranked. The groups cover only the top results the first run allowed, so total can be larger than the number of grouped messages. Neither number counts every match in the mailbox, so use --mode lexical when you need exact counts.

mxr cat, mxr thread, mxr headers, and mxr export --format json return fuller daemon payloads because they are read surfaces, not compact search rows. Prefer mxr search --format ids when you only need IDs. When you only need to say what a thread is, mxr thread-preview <id>... returns up to 100 threads’ subject, latest sender (sender_name, sender_email), latest_at (unix seconds), snippet, message_count, unread_count and an attachment flag, with no bodies. --format csv writes a header line naming the columns, then one row per thread: thread_id, subject, sender_name, sender_email, latest_at, message_count, unread_count, the attachment flag, then snippet; fields with commas, quotes or newlines are quoted, and other control characters in mail text become spaces. It is a separate read from mxr search, whose rows have no such flag.

Terminal window
mxr search 'from:sarah@example.com after:2026-04-23' --format ids \
| mxr archive --dry-run

--format ids prints one ID per line. Mutations with omitted positional IDs read that form from stdin.

Terminal window
mxr search 'label:newsletters older_than:30d' --format ids \
| mxr archive --dry-run

This is safer and more portable than xargs -r on macOS.

mxr search --format ids writes paging state to stderr as # comment lines, so stdout stays clean for the pipe. Both lines are conditional: the first is skipped only when the page holds every match and --offset is 0, and the second appears only when a next page exists.

# search page: returned=50 total=73 offset=0
# more results: rerun with --offset 50

mxr subscriptions --rank --format json returns an array of subscription sender records. --rank sorts by opened_count / message_count ascending, then by archived_unread_count descending.

Terminal window
mxr subscriptions --rank --format json \
| jq '.[0] | {
sender_email,
message_count,
opened_count,
replied_count,
archived_unread_count
}'
Field Type Notes
sender_email string Sender address for the bucket; grouping is case-insensitive.
message_count number Non-trash, non-spam messages from that sender with an unsubscribe method.
opened_count number Messages in the bucket whose local READ flag is set. This is not tracking-pixel telemetry or distinct open events.
archived_unread_count number Messages that are archived while still unread; tie-breaker for --rank.
replied_count number Stable JSON field, currently 0 for subscriptions; reply-pair counts power sender/contact analytics, not this ranker.

If opened_count == message_count, every message in that sender bucket is read locally. That can come from the mxr read command, another mail client, provider-side read state, filters, or bulk mark-read actions.

mxr reading --format json (or edition --peek --format json, which doesn’t count as a visit) prints the edition. Each item is a readable item, not a message; its item_key feeds mxr reading open, later --add and let-go.

{
"header": "Newsletters you chose, as an edition. Read when you like.",
"bands": [
{
"band": "since_last_visit",
"label": "Since you were last here",
"items": [
{
"item_key": "0198c2f4-…:0",
"kind": "issue",
"shape": "single",
"title": "The quiet death of the three-pane layout",
"standfirst": "Every reader since 2002 shipped the same window…",
"source": "Long Reads Weekly",
"words": 450,
"minutes": 2,
"expires_at": "2026-10-21T00:07:00Z",
"why": "Here because: has List-Unsubscribe (rule). Fades Tuesday 21 Oct unless you keep it.",
"lead": true,
"engagement": "you read 8 of 10",
"links": [],
"on_later": false,
"progress": 0.0,
"article_cached": false
}
]
}
],
"left_off_here": true,
"later_count": 1,
"sources": [{ "name": "Growth Digest", "evidence": "You opened 0 of the last 11 issues", "window_days": 14.0, "suggest_unsubscribe": true, "unsubscribe": "one_click" }],
"pace_wpm": 250,
"pace_measured": true
}

band is since_last_visit, earlier or fading; shape is single, digest, teaser or notice. A digest’s links sit in links, each with its own item_key, domain and tracked (the link goes through a click tracker, so domain is the tracker’s). There is no unread field anywhere in Reading. --format jsonl prints one item per line and --format ids the item keys.

To do rows, Updates lines and Reading items may include source_filed_at, an RFC3339 timestamp. It records when mxr observed the source email leave the provider inbox through sync, while that removal is still the latest relevant inbox transition. It does not record task completion, a mode done mark, or the provider’s original archive time. Sync evidence alone does not identify who removed the email or whether a person or automation did it.

Surface Source described Other dates with separate meanings
To do row source_message_id source_date is the source email’s stored date; act_by_at and due_at describe the task.
Updates line latest_message_id, even when fact_message_id is older latest_at is the newest email’s date, not its filing date. Parcel tracker lines have no filing timestamp.
Reading item message_id, in the edition or Later shelf arrived_at is the source email’s date; expires_at is its edition expiry and is absent on Later.

The optional field is omitted when there is no current qualifying evidence. Older daemons also omit it. Absence is not proof of inbox membership: mail first discovered already archived has no observed removal, and a later local archive supersedes an earlier sync event. A return to the inbox clears the marker. None of these cases should be interpreted as “finished”.

Updates and Reading retain eligible externally filed mail, subject to their normal mode rules. Inspect Reading items with filing evidence without recording a visit:

Terminal window
mxr reading edition --peek --format json \
| jq '[.bands[].items[], .later[]]
| map(select(.source_filed_at != null)
| {item_key, message_id, arrived_at, source_filed_at, on_later})'

[] means no returned item has this marker. For digest lines, use the Updates example.

Inspect the row metadata with:

Terminal window
mxr todo --format json
mxr updates --format json

These fields describe local row attention, not the source email’s READ flag:

Field Type Meaning
id string Row identity; pass it as row_id to bridge/MCP acknowledgments.
account_id string Owning account ID; copy it from the row, not an account display name.
unread optional boolean true means this revision is unseen; false means it was acknowledged. Absence is unknown, not a seen receipt.
seen_revision optional string Opaque 64-character hexadecimal content revision; pass it unchanged as revision.

The same metadata appears on To do runway, catch-up, detail and change rows, Updates lines, and those rows nested in Now. Older payloads can omit the optional fields. Do not derive a revision from a timestamp or source read flag.

Acknowledgment is a separate operation:

Terminal window
mxr modes seen todo TODO_ID --account ACCOUNT_ID --revision SEEN_REVISION --dry-run --format json
mxr modes seen todo TODO_ID --account ACCOUNT_ID --revision SEEN_REVISION --format json

The preview returns {"seen":false,"dry_run":true}; applying returns {"seen":true,"dry_run":false}. JSONL returns that same object on one line. The receipt means the supplied revision was recorded, not that it is still the row’s current revision. Fetch the row again to inspect its current unread value. Task completion, update let-go and provider read state are unchanged. See MCP input mapping and the HTTP route.

--dry-run on a core mail mutation returns one preview object:

{
"action": "archive",
"dry_run": true,
"requested": 2,
"selected_messages": 2,
"selected_threads": 1,
"message_ids": [
"019706f4-9b6e-7c31-8a3f-2a1c4de50b91",
"019706f5-1d02-7a48-b0c7-6e5f9a2d4413"
],
"messages": [
{
"message_id": "019706f4-9b6e-7c31-8a3f-2a1c4de50b91",
"from": "Alice",
"subject": "Quarterly review"
}
]
}

requested and selected_messages both hold the resolved message count. mxr unsubscribe <address> is the exception: each address sends at most one request, so its dry run also reports request_count (0 or 1 per address), already_unsubscribed (1 when the chosen message already has a receipt), requests (the one message_id and method per address) and addresses, one entry per address with the same per-address fields. The top-level requested, selected_messages, message_ids, messages and request_count are totals across the addresses. See the unsubscribe guide. selected_threads counts the distinct threads those messages belong to, and falls back to the message count when the envelopes could not be resolved. messages[].from is the sender’s display name, falling back to their address when the message carries no display name. The full Name <address> form never appears here, so match on message_id instead of parsing from. subject reads (no subject) when the subject is empty. Both fields are empty strings for a message whose envelope did not resolve. messages[].unsubscribe_method appears on mxr unsubscribe --dry-run preview records, for every message whose envelope resolved. The value is OneClick, HttpLink, Mailto, BodyLink, or None.

--format jsonl emits one preview line per message, without the counts:

{"action":"archive","dry_run":true,"message_id":"019706f4-9b6e-7c31-8a3f-2a1c4de50b91","from":"Alice","subject":"Quarterly review"}

Searches that match more than 1,000 messages

Section titled “Searches that match more than 1,000 messages”

A --search selection holds at most the newest 1,000 matches, whatever search.default_mode is: it always searches lexically, newest first. When the daemon reports more visible matches than that, the dry-run preview, the result and the archive object gain one field, in addition to the ones shown here (--format jsonl repeats it on each line):

{ "capped": true }

The field is absent when the selection holds every match and for explicit or piped IDs, which have no cap. There is no count of the matches left out: the daemon can tell whether another visible match exists, not how many. The same notice goes to stderr before any change, or into the dry-run preview and confirmation prompt in table output:

More than 1,000 messages match; only the newest 1,000 are selected. Narrow the search to reach the rest.

archive, read-archive, label and unlabel can act on every match instead (below); their notice says so:

More than 1,000 messages match; only the newest 1,000 are selected. Pass --all to act on every match, or narrow the search.

mxr archive, read-archive, label and unlabel take --all with --search. The daemon resolves the whole search, lexically and newest first, with the same visibility and trash/spam rules as mxr search. No message ID list crosses the socket in either direction, so the output below is the same size for ten matches and for half a million. --all conflicts with message IDs and --async. Other commands keep the newest-1,000 cap.

--all --dry-run prints the exact count and a sample of the 20 newest messages (capped is always false):

{
"action": "archive",
"dry_run": true,
"all": true,
"selection": { "kind": "search", "query": "from:noreply@example.com" },
"selected_messages": 70412,
"selected_threads": 51870,
"accounts": [
{ "account_id": "019706f4-0000-7000-8000-000000000001", "account_name": "Work", "count": 70412 }
],
"messages": [
{
"message_id": "019706f4-9b6e-7c31-8a3f-2a1c4de50b91",
"account_id": "019706f4-0000-7000-8000-000000000001",
"thread_id": "019706f4-9b6e-7c31-8a3f-2a1c4de50b92",
"from": "Alice",
"subject": "Quarterly review",
"date": "2026-10-28T09:12:00Z"
}
],
"sample_size": 20,
"capped": false,
"undoable": false,
"preview_token": "<preview-token>",
"expires_at": 1761600000000
}

selection.account_id appears when --account names one. selected_messages is the exact number of messages the job will change. undoable is always false: an --all job cannot be undone, so this preview is the check. The table output and the confirmation prompt say so too. messages is the sample, never the whole selection, and there is no message_ids or requested field. preview_token is absent when nothing matched. It is single use and valid for 10 minutes: --all --preview-token TOKEN runs exactly the messages that preview counted, and mail that arrives later is left alone. --format jsonl prints one line per sample message, each carrying selected_messages, selected_threads and capped. --format csv and --format ids are refused with --dry-run, because they would need the full list.

--all --yes starts one job, waits for it (progress goes to stderr) and prints it. --no-wait prints it as soon as the daemon has accepted it. The job is the only place its ID appears:

{
"action": "archive",
"dry_run": false,
"all": true,
"selection": { "kind": "search", "query": "from:noreply@example.com" },
"selected_messages": 70412,
"selected_threads": 51870,
"job": {
"job_id": "<job-id>",
"kind": "mutation.archive",
"status": "succeeded",
"progress": { "total": 70412, "completed": 70412, "succeeded": 70412, "skipped": 0, "failed": 0 },
"undo_ids": [],
"started_at": 1761600001000,
"finished_at": 1761603601000
},
"capped": false
}

--format ids prints the job ID alone and --format csv has a job_id column. A job that ends failed makes the command exit non-zero, with the counts and the first failing message in the error. skipped counts messages that left the mailbox after the preview. undo_ids is always empty: the job keeps no undo. A message a provider’s rate limit stopped half way (read-archive marked it read, then the archive was refused) is finished when the job retries after the wait. mxr jobs JOB_ID shows the same job later: failures holds the first 50 failing messages with the provider’s error (the exact total is progress.failed), paused_until is set while the job waits out a provider rate limit and resumes by itself, and a daemon restart ends a running job as failed (“interrupted”) with the counts it had persisted.

A label edit acts on the labels the dry run resolved, in each account the search reaches, whatever they are called by the time the job runs: renaming Work after the preview, or making a new label called Work, does not change which label is edited. If a label the preview resolved is deleted (or is no longer one you created) before the job starts, --yes is refused with the label … changed since the preview …; preview again. Labels are checked only in the accounts the search reaches. The search can be at most 2,048 bytes and a label edit can name at most 8 labels of at most 512 bytes each.

mxr undo JOB_ID on an --all job refuses with an error that says the job ran with --all and cannot be undone, not that the id was not found; mxr undo JOB_ID --dry-run refuses with the same error and exit code. An agent or MCP profile gets that refusal only when it is allowed every account the job touched; otherwise it gets the usual not-found. To reverse a run, act on a search the other way (unlabel --all after label --all).

mxr undo MUTATION_ID --dry-run changes nothing. It asks the daemon for the same lookup the undo makes, so an unknown, expired or already undone id is refused with the undo’s own error and exit code. A valid id with something left to restore lists its message targets and whether it also carries desk state. The preview checks local message availability and highlight restoration; it can refuse an entry as irreversible when no local work remains to restore. Its JSON adds a preview object (absent on a real undo):

{
"mutation_id": "mut_123",
"dry_run": true,
"undone": false,
"preview": {
"mutation_id": "mut_123",
"kind": "archive",
"targets": [
{ "message_id": "msg_1", "account_id": "acc_1", "in_local_store": true }
],
"restores_desk_state": false
}
}

in_local_store: false marks a message that is gone from the local store. When other targets remain restorable, the undo leaves it out. Provider access and other restoration steps can still fail when the real undo runs; the preview does not contact a provider.

mxr jobs JOB_ID carries the first 50 failures and every undo_id; undo_id_count and failure_count say how many the job holds. Jobs other than --all (a sweep, --async) are undone from that list. The mxr jobs listing carries neither list: undo_ids and failures are empty there, and the two counts say how many mxr jobs JOB_ID shows. Every error and failure reason is cut to 512 bytes (an account name to 128) when the job is saved, so a listing of the 100 retained jobs stays well under the 16 MiB frame limit. A selection job also carries action, the label edit or archive it applies, so a start repeated under the same job id with a different action is refused. A job id is only ever returned for a job the daemon has recorded: a start that loses the preview token to another start is refused and leaves no job. If the connection drops before the daemon replies to --all --yes, the command looks for the job under its id for 10 seconds; if it still has not appeared, the command exits non-zero saying the outcome is unknown, with the job id and mxr jobs JOB_ID to check it, because the start may still be in progress.

The dry run’s sample cuts each message’s from and subject to 256 bytes, and account names to 128, so a preview stays small whatever the mail holds.

mxr unsubscribe <address> reports it per address: the address’s entry in addresses carries capped, and the top level carries it when any address does. With --format jsonl, each dry-run line of a capped address carries capped. The request it sends still comes from the newest message.

Archive, trash, spam, read, star, label, and move report the selection at the top level and the per-account outcome under a nested result:

{
"action": "archive",
"dry_run": false,
"selected_messages": 2,
"selected_threads": 1,
"message_ids": [
"019706f4-9b6e-7c31-8a3f-2a1c4de50b91",
"019706f5-1d02-7a48-b0c7-6e5f9a2d4413"
],
"result": {
"requested": 2,
"succeeded": 2,
"skipped": 0,
"failed": 0,
"accounts": [
{
"account_id": "0196b21c-4e80-7f0a-9c3d-71b8ee402f55",
"account_name": "work",
"succeeded": 2,
"skipped": 0,
"failed": 0,
"error": null
}
],
"mutation_id": "019706f7-3a55-7b02-8e11-5d0c9f6a2b34"
}
}

result.mutation_id is set by the undoable mutations (archive, trash, spam, read, read-and-archive, star, label and move) and is what you pass to mxr undo. When an undoable mutation lands but its undo entry could not be written, mutation_id is absent and "undo_unavailable": true takes its place.

Mutations the daemon only acknowledges emit the same top-level fields with "ok": true instead of result. One dispatched as a background job returns action, dry_run, message_ids, and a job object; poll it with mxr jobs <job_id>.

These three walk the selection one message at a time, so they report a flat batch shape with no nested result:

{
"action": "unsubscribe",
"dry_run": false,
"requested": 3,
"succeeded": 2,
"failed": 1,
"selected_messages": 3,
"selected_threads": 2,
"message_ids": [
"019706f4-9b6e-7c31-8a3f-2a1c4de50b91",
"019706f5-1d02-7a48-b0c7-6e5f9a2d4413",
"019706f6-2c11-7d63-9b40-8ad3c5e21f07"
],
"errors": [
{
"message_id": "019706f6-2c11-7d63-9b40-8ad3c5e21f07",
"error": "no unsubscribe method"
}
]
}

requested here is the length of message_ids, and failed is the length of errors. selected_messages and selected_threads are omitted when the command has no selection to report, as with mxr unsnooze --all. mxr snooze --dry-run and mxr unsubscribe --dry-run still use the preview shape above.

mxr invite show MESSAGE_ID --format json returns one invite object. mxr invites list --format json returns an array of the same shape; --format jsonl emits one object per line.

Terminal window
mxr invite show MESSAGE_ID --format json
{
"id": "018f8c0f-7b78-7c44-9f48-3e5a0ef4f7aa",
"account_id": "0196b21c-4e80-7f0a-9c3d-71b8ee402f55",
"message_id": "019712a3-88d4-70e9-b5a2-4c9f0d61e7aa",
"metadata": {
"method": "REQUEST",
"component_kind": "VEVENT",
"uid": "meeting-123@example.com",
"sequence": 2,
"recurrence_id": null,
"summary": "Planning session",
"starts_at": "20260518T140000Z",
"ends_at": "20260518T143000Z",
"location": "Room 3",
"organizer": {
"email": "alice@example.com",
"name": "Alice"
},
"attendees": [
{
"email": "you@example.com",
"name": "You",
"partstat": "NEEDS-ACTION",
"role": "REQ-PARTICIPANT",
"rsvp": true
}
],
"warnings": []
},
"created_at": 1778832070,
"updated_at": 1778832070
}

Important fields:

Field Type Notes
message_id string Pass to mxr invite reply, mxr thread, or mxr cat.
metadata.method string Calendar method such as REQUEST, CANCEL, or REPLY. RSVP sending only supports actionable REQUEST invites.
metadata.uid string iCalendar UID. Used with sequence and recurrence identity for update safety.
metadata.sequence number or null Higher sequence means a newer invite update exists.
metadata.recurrence_id string or null Identifies one instance of a recurring event.
metadata.raw_ics string or null Raw local calendar text, useful for debugging and dry-run inspection.
metadata.warnings string[] Parser or safety warnings to show before replying.

mxr invite reply MESSAGE_ID accept --dry-run --format json returns the preview directly. Without --dry-run, it sends and returns the result directly.

Terminal window
mxr invite reply MESSAGE_ID accept --dry-run --format json
{
"message_id": "019712a3-88d4-70e9-b5a2-4c9f0d61e7aa",
"action": "accept",
"attendee_email": "you@example.com",
"organizer_email": "alice@example.com",
"subject": "Accepted: Planning session",
"body_text": "You accepted this invitation.",
"ics": "BEGIN:VCALENDAR\nMETHOD:REPLY\n...",
"warnings": []
}

Successful sends return:

{
"message_id": "019712a3-88d4-70e9-b5a2-4c9f0d61e7aa",
"action": "accept",
"provider_message_id": "provider-id-or-null",
"rfc2822_message_id": "<mxr-generated@example.local>"
}

mxr messages --format json returns the bands:

{
"header": "People you talk with, one row each. Reply or mark done.",
"your_turn": [
{
"id": "person:samir@launchpad.example",
"kind": "person",
"band": "your_turn",
"title": "Samir Patel",
"closeness": "close",
"your_turn": true,
"preview": { "kind": "latest", "text": "Can you take a look and reply with the next concrete step?" },
"pace_label": "usually 47m",
"topics": [
{ "subject": "Contract renewal", "shape": "one_to_one", "state": "your_turn" }
],
"why": "Here because: Samir replied to your message, and you write to each other often (rule)."
}
],
"pinned": [], "recent": [], "quiet": [],
"recent_total": 12, "quiet_total": 30, "row_count": 43, "thread_count": 61,
"merge_suggestion_count": 1
}

preview.kind is ask (the verbatim ask from a cached gist, with model), latest or you. mxr messages person ID --format json adds relationship_line, every topic, and conversation.messages[], each with text (the new text), trimmed: {quote, signature}, trimmed_label and layout (compact or letter). trimmed also has footer (a disclaimer or unsubscribe footer), and only_quoted is true when a message was nothing but quoted text. mxr messages ack THREAD --dry-run --format json returns the exact text and html parts, from, to, subject, built_from, countdown_seconds, preview_token and preview_expires_at; sent_message_id is set only after a real send.

mxr records --format json prints the ledger: total (every record), matching (records the filter kept), records (this page, newest first), months (every matching month, newest first, with count and one total per currency in totals), facets (kinds, issuers, years as {value, label, count}, plus has_pdf, checked, unchecked), coming_up, filter, and when they apply issuer, empty_state and first_run. --format jsonl prints one record per line.

A record (trimmed, from the demo mailbox):

{
"id": "rec_082186e6215c42bfbe4c7ac3eaa682ef",
"kind": "order",
"kind_label": "Order",
"issuer": "Amazon.com",
"title": "Delivered Amazon.com package",
"reference": "112-7480913-6624530",
"reference_label": "Order",
"date": "2026-10-06T12:00:00Z",
"checked": false,
"unchecked_fields": ["delivered_at", "issued_at"],
"stage_line": "shipped · delivered 7 Oct",
"document_count": 0,
"source_count": 3,
"why": "Here because: \"delivered:\" in the subject (unchecked).",
"origin": "rule",
"fields": [
{
"field": "delivered_at",
"label": "Delivered",
"value": "Wed 7 Oct 2026 06:12",
"copy": "Wed 7 Oct 2026 06:12",
"source": "delivery",
"source_label": "the delivery tracker",
"checked": false,
"evidence": "the delivery tracker",
"message_id": "b5a7c90b-10e9-5738-9799-27cf1ea28172"
}
]
}

amount is {minor, currency, display} when the record has one; date is the transaction’s date, else the newest email’s. A date with no time of day is stored at 12:00 UTC so it reads as the same day everywhere. Each entry in fields is the winning value of one field: source is schema, rule, delivery, todo or user, and checked is false for an amount or date nobody has confirmed. mxr records show adds documents, sources (the emails, with their stage) and issuer_records. group is the trip or series ({id, kind, title, count, span_start, span_end}).

mxr records ask "lisbon booking ref" --format json:

{
"query": "lisbon booking ref",
"asked": "reference",
"answer": {
"field": "reference",
"label": "Booking ref",
"value": "K7QX2M",
"copy": "K7QX2M",
"provenance": {
"field": "reference",
"source": "schema",
"source_label": "schema.org markup",
"checked": true,
"evidence": "K7QX2M"
},
"record": { "id": "rec_810960585d424fdf92aeefce6680819a", "kind": "booking" }
},
"mode": "answer",
"matching": 3,
"also": [{ "id": "rec_dde42d9377554b539e34762a1fd18d2e" }]
}

asked is reference, amount, date, document or any. matching counts every record that matched. mode is answer or list: a query that only names something several records match (mxr records ask octopus), or any query with --all, comes back as list, with list holding {header, count, offset, records, months, totals, first, last, top_record_id, issuer?}. records is one page of the matches, newest first; count, months and totals (one per currency, never converted) cover every match; top_record_id is the best match, also on answer; issuer is set when every match shares one. With no match, answer is absent and fallback carries note and mxr ask’s answer (or error). --format ids prints the answer’s copy value alone, ready for a pipe, or in list mode the page’s record ids, one per line.

mxr records export --csv --dry-run --format json reports what an export would write, from the same rows:

{
"dry_run": true,
"rows": 7,
"totals": [{ "minor": 172966, "currency": "GBP", "display": "£1,729.66" }],
"unchecked": 7,
"missing_pdfs": 4,
"by_kind": [
{ "value": "invoice", "label": "Invoice", "count": 1 },
{ "value": "receipt", "label": "Receipt", "count": 2 },
{ "value": "statement", "label": "Statement", "count": 4 }
],
"summary": "7 records, £1,729.66. 7 have an unchecked amount or date; 4 have no PDF.",
"pdfs_copied": 0
}

mxr records fix, dismiss, file and sender print a change: {dry_run, action, records, message, undo?}, where message is the toast (“Filed in Archive.”) and undo says how to reverse it (restore, dismiss, clear_fields or sender, with record_ids and fields).

mxr updates --format json prints the digest at the latest cut:

{
"cut": { "at": "2026-10-06T15:30:00Z", "label": "16:30", "title": "Yesterday afternoon's digest",
"previous_at": "2026-10-06T07:00:00Z", "next_at": "2026-10-07T07:00:00Z",
"next_label": "08:00", "cuts": ["08:00", "16:30"] },
"headline": "8 need a look, 6 changed. 149 routine from 5 sources.",
"message_count": 171,
"source_count": 12,
"needs_a_look": [ { "source_name": "Google", "fact": "Security alert: New sign-in from Chrome on Windows",
"signal": "needs_you", "count": 1, "time_label": "14:30",
"todo_id": "todo_63be0b7c784d4adcb86d4c5b9e7c79b7", "in_todo": "already in To do" } ],
"changed": [ { "source_key": "strava.com", "fact": "Your week in running: 21.3 km over 3 runs",
"numbers": [ { "raw": "21.3 km", "value": 21.3, "unit": "km" },
{ "raw": "3 runs", "value": 3.0, "unit": "run" } ],
"delta": { "raw": "21.3 km", "previous_raw": "19.0 km", "change": 12.105263157894742,
"text": "up 12% on last week" } } ],
"routine": [ { "source_key": "vercel.com", "fact": "Deployment succeeded for acme-web", "count": 4 } ],
"since": { "label": "arriving for 08:00", "message_count": 17, "source_count": 3, "lines": [] },
"selection_token": "cb3d3cd1e8b7ff66",
"let_go_line": "Let go of 213 updates from 13 sources, 42 of them not shown (tuned or expired); 6 also in To do stay there."
}

From the 2,000-message demo; lines are trimmed here. Every line also carries id, section, account_id, message_ids, thread_ids, latest_message_id, latest_at, why, setting, todo_title, auto_todo (on alerts: state of created or not_created, reason_code, reason_text) and provenance (where each field came from: rule, code or default), and, where they apply, link (url, domain), tracker (kind of parcel, build or incident, with state and outcome). Parcel trackers retain steps and step for existing clients and may also include items (available item records with name and optional quantity), tracking_number, and order_number. These identity fields are optional and absent from older responses. suggestion is also optional. With --expired, expired lists updates past their window. --format jsonl prints one line per source line with section set to needs_a_look, changed, routine, since or expired. --format ids prints thread ids.

A line from an email that gives a one-time code also carries code ("482913"), while the code is in its window.

mxr updates let-go --format json returns dry_run, line, message_count, source_count, hidden_count, in_todo_count, thread_ids, message_ids, selection_token, one items outcome per thread (as mxr modes done) and mutation_id for mxr undo.

mxr code --format json prints the newest one-time code still in its window, from mail received in the last day in any folder but Trash and Spam:

{
"code": "482913",
"current": true,
"expires_at": "2026-10-22T14:42:00Z",
"received_at": "2026-10-22T14:32:00Z",
"sender_name": "Acme",
"sender_host": "acme.example",
"sender_email": "no-reply@acme.example",
"subject": "Your verification code is 482913",
"account_id": "…",
"message_id": "…",
"thread_id": "…"
}

sender_name is the name the sender chose; show sender_host beside it. expires_at is the code’s own lifetime, not the email’s Updates window. Mail dated more than five minutes ahead of this machine’s clock is left out. --all prints an array of the last day’s codes, newest first, with current: false on expired ones. --format ids prints the code alone. With no current code it exits non-zero. The bridge serves the same list at GET /api/v1/mail/codes (account, limit).

A task with a later-message offer includes resolution in its mxr todo --format json row. The offer identifies the exact source and quote, and includes the proposed action and optional new deadline. A missing resolution means there is no current offer.

Terminal window
mxr todo --format json
{
"resolution": {
"id": "offer_…",
"message_id": "019…",
"thread_id": "019…",
"source_date": "2026-10-10T09:30:00Z",
"quote": "Your renewal is now due on 24 October.",
"quote_location": "body",
"source_method": "rule",
"action": "revise_date",
"proposed_due_at": "2026-10-24T00:00:00Z",
"proposed_due_words": "due on 24 October",
"status": "pending"
}
}

action is complete or revise_date; status is pending, accepted, dismissed, undone or superseded. The row is a suggestion only: mxr todo resolve TODO_ID SUGGESTION_ID preview validates and previews it, while accept applies it. See Review later evidence for the full review and undo flow.

Terminal window
# Senders by volume from compact search rows
mxr search 'newer_than:7d' --format json \
| jq -r '.results
| group_by(.from)
| map({sender: .[0].from, count: length})
| sort_by(-.count) | .[]
| "\(.count)\t\(.sender)"'
# Subjects from a sender (jsonl stdout is bare records, so no .results here)
mxr search 'from:legal@example.com' --format jsonl 2>/dev/null \
| jq -r '.subject'
# Check whether more pages remain
mxr search 'has:attachment' --limit 200 --format json \
| jq '.paging | {total, has_more, next_offset}'
# IDs from attachment-bearing matches
mxr search 'has:attachment older_than:30d' --format ids
# Copy a booking reference
mxr records ask "lisbon booking ref" --format ids | pbcopy
# Records with an unchecked amount, before an export
mxr records list --unchecked --format jsonl | jq -r 'select(.unchecked_fields | index("amount")) | .id'
# Invite IDs to inspect before replying
mxr search 'has:calendar newer_than:30d' --format ids \
| xargs -I{} mxr invite show {} --format json