Accounts
Account model
Section titled “Account model”mxr distinguishes between:
- Runtime accounts: what the daemon is actually running now
- Config-backed accounts: editable account definitions used to produce runtime accounts
The TUI Accounts page is built from runtime inventory, not from config file entries alone.
TUI accounts page
Section titled “TUI accounts page”Open it with:
gthenCgC, or:then Settings
Actions:
j/k: move account selectionc: new IMAP/SMTP accountEnter/o: edit selected accountt: test selected accountd: set default accounti: edit the selected account’s colour and tag. The firstEnterpreviews the change with the daemon, and the nextEntersaves itr: refresh runtime account inventory
The page shows:
- Details on the left
- Account list on the right
- Runtime Gmail, Outlook, IMAP, and SMTP-backed accounts
- Editable config-backed accounts where supported
- Default-account state
- Provider kind and enabled state
- Last test/status messaging
CLI account actions
Section titled “CLI account actions”mxr accountsmxr accounts add gmailmxr accounts add outlook # Outlook.com, Hotmail, Livemxr accounts add outlook-work # Microsoft 365 work or schoolmxr accounts add imapmxr accounts add smtpmxr accounts show ACCOUNTmxr accounts test ACCOUNTmxr accounts identity ACCOUNT --color amber --tag W --dry-runColour and tag
Section titled “Colour and tag”Every account has a colour and a tag, so mixed lists can say which account a
row came from. The TUI puts the tag in a coloured chip before the date on each
email row whenever a list mixes accounts, and names the account in the reader
header. The CLI shows it in mail tables (see the ACCT column below), and the
Raycast extension labels rows with the account’s config key. The daemon gives an account its
colour and its tag when the account is created, and keeps both.
The tag comes from the account’s name: “Work” is W, “Planetary Escape” is
PE. If that tag is taken, the name gives more letters or a digit, so
Wedding becomes WE. Renaming an account does not change its tag.
mxr accounts lists each account’s tag and colour. The JSON output carries
the same values under identity.
To change them, pass --color (one of sky, amber, green, yellow,
blue, vermilion, purple, slate), --tag (1 to 3 letters or digits), or
both. Add --dry-run to see the change without writing it:
mxr accounts identity work --color amber --tag W --dry-runmxr accounts identity work --tag OFF$ mxr accounts identity work --color amber --tag W --dry-runWould set identity for account 'work' (before: tag DW, colour amber; after: tag W, colour amber). ok Dry run only; no changes made.A tag already used by another account is refused, and the error names that account:
$ mxr accounts identity work --tag DP --dry-runFailed to set identity for account 'work'. error Tag 'DP' is already used by account 'Demo Personal'.An unknown colour is refused before anything is written, with the list of
valid slots. The same values can be set in config; see
accounts in the config reference.
Mail tables from mxr search, mxr threads, mxr messages, mxr now,
mxr todo, mxr updates and mxr reading show the tag, in an ACCT column
where the table has columns. The tag appears only when you have more than one
enabled account and the command was not given --account. Scripts that read
JSON or JSONL get account_id on each row, as before.
$ mxr threads --limit 3 --format tableDP 2026-10-22 22:25 1 msgs (1 unread) Boiler service at the flatDP 2026-10-22 22:05 1 msgs (1 unread) Okafor Lettings: tenant news for OctoberDW 2026-10-22 21:58 2 msgs (0 unread) Launch checklist for Project AuroraOwned addresses and aliases
Section titled “Owned addresses and aliases”An account owns its configured account email plus any aliases you register.
mxr uses that set, together with the provider’s sent mark, to classify mail as
inbound vs outbound, and to let you send from any of them. Mail is outbound when
its From is one of your owned addresses, or when the provider marks it as sent.
Gmail’s SENT label marks mail sent from a Gmail send-as address, so that mail
counts as sent even if you have not added the address as an alias. Over IMAP, mxr
marks mail as sent from Gmail’s labels and from a folder named in English, such
as Sent, Sent Items, Sent Mail or Sent Messages. A localised Sent folder
does not count yet: mxr reads the folder’s special-use attribute to label the
folder, but does not carry it into each message’s sent mark. Screening still follows owned addresses only: a message from a
screened sender is screened unless its From is one of your addresses, whatever
the sent mark says.
The current primary address cannot be removed; remove fails
with cannot remove the primary address; set another address as primary first,
so promote another address with set-primary first.
mxr accounts addresses list --account workmxr accounts addresses add --account work accounts@planetaryescape.xyzmxr accounts addresses add --account work support@planetaryescape.xyzmxr accounts addresses set-primary --account work hello@planetaryescape.xyzmxr accounts addresses remove --account work support@planetaryescape.xyzAdding or removing an address reclassifies the account’s stored mail against the new set in the same command. Mail from an address you now own reads as sent, and mail from an address you no longer own reads as received, unless the provider filed it as sent. Reply pairs follow in the same command. The contacts table is rebuilt in the background, starting about ten seconds after the last change; a contacts or analytics view already open shows the new counts after you reload it. A sync pass that was already running when you made the change is reconciled before it releases its place in line, so the messages it wrote take the new direction and their reply pairs are rebuilt with them. The catch is timing: until that pass finishes, a message it wrote can still show the old direction, for as long as the pass runs. If the reconciliation fails, it is retried after the account’s next successful sync pass. Relationship profiles and resolution suggestions are not refreshed by an address change yet.
Arrival history is not rewritten. An arrival records what arrived when it arrived, and a correction you made stays as you made it. So mail you sent from a new alias may still appear in an old arrival count, and mail from an alias you removed is not added to arrival counts after the fact. The command reports how many messages changed:
mxr accounts addresses add --account work support@planetaryescape.xyz# Added support@planetaryescape.xyz. Stored mail reclassified: 14 now sent, 0 now received.mxr accounts addresses add --account work support@planetaryescape.xyz --format json# {"email":"support@planetaryescape.xyz","dry_run":false,"to_outbound":14,"to_inbound":0}Add and remove take --dry-run. It prints the same counts the real change
would apply and changes nothing: the address, the stored directions and the
arrivals stay as they are. Run it first when you want to see the effect:
mxr accounts addresses add --account work support@planetaryescape.xyz --dry-run# Dry run: nothing changed. Added support@planetaryescape.xyz. Would reclassify stored mail: 14 now sent, 0 now received.mxr accounts addresses remove --account work support@planetaryescape.xyz --dry-run --format jsonset-primary has no dry run. It changes only the primary marker, so it never
changes which addresses are owned. It still runs the account-wide
reconciliation, so its counts can be non-zero when rows from an earlier change
were stale.
Once an address is registered it becomes a valid sender inside mxr for that
account. A reply defaults its From to whichever owned address the original was
delivered to, and --from / the from: frontmatter field can send as any
owned address. See Sending from an alias.
Only the account’s own registered addresses are accepted; an unowned From is
rejected before the message is sent.
Register the alias with your mail provider first. Adding it to mxr does not create the address at Zoho, Gmail, or another SMTP provider, and it does not grant provider-side send-as permission. Confirm mxr’s local sender resolution before sending:
mxr compose --from accounts@planetaryescape.xyz --to alice@example.com \ --subject "Invoice 42" --dry-run --format jsonWhat you get: a preview whose from field names the exact address mxr will
hand to the provider. The provider can still reject an alias it has not
authorised.
The address registry also has an is_primary marker. In mxr 0.6.12,
set-primary and add --primary change that marker; they do not rewrite the
configured account email or the default From used by an account-key selector.
Existing aliases stay registered and remain valid per-message senders:
mxr accounts addresses add --account work hello@planetaryescape.xyz --primarymxr accounts addresses list --account work --format tableWhat you get: hello@planetaryescape.xyz marked as primary in the owned-address
inventory, with the previous primary retained as a non-primary owned address.
Use an exact owned address with mxr compose --from <address> when you need
that address as the visible From.
After you change an address
Section titled “After you change an address”Adding, removing or promoting an address updates the daemon’s set of owned addresses at once. Reply and forward recipients, thread summaries and triage verdicts all read from that set, so they follow the change: a cached summary or triage verdict made under the old set is rebuilt the next time it is read, and the TUI drops the reply recipients it had prepared. The daemon announces the change as an event. Watch for it while you make one:
mxr eventsmxr accounts addresses add --account work support@example.comWhat you get: account addresses changed account=<account-id> in the
mxr events stream. A config reload that changes an account’s addresses
sends the same event.
Sync decides each new message’s direction (inbound or outbound) from the owned
set and the provider’s sent mark. If the daemon cannot rebuild that set, it stores new mail with direction
Unknown instead of guessing, and mxr doctor warns:
Account address cache is stale — new sync messages get Unknown direction until it rebuildsThe JSON report has the same signal as address_cache_stale. Run mxr sync, as
the finding suggests. Once the set rebuilds, the next sync
pass reclassifies the Unknown rows.
Registering an alias reclassifies mail that is already stored. Messages you sent from an alias you never registered still count as sent when Gmail marks them SENT, as it does for send-as addresses.
Selecting an account
Section titled “Selecting an account”mxr accounts --format tablemxr search "is:unread" --account work --format jsonmxr archive --account work --search "from:noreply@example.com older_than:30d" --dry-runWhat you get: the account selectors available locally, account-limited search results, and a preview of the matching work-account messages before any mutation runs.
Most mail-facing CLI commands accept --account <selector>.
The selector can be:
- account key
- email address
- account id
- display name, when it matches exactly one account
Use the same selector on reads, lists, replies, and drafts:
mxr search "is:unread" --account work --format jsonmxr count "from:notifications@github.com" --account you@example.commxr archive --account work --search "from:noreply@example.com older_than:30d" --dry-runmxr reply MESSAGE_ID --account work --body "Thanks, will do." --dry-runmxr drafts --account personal --format jsonIf you omit --account, mxr keeps the command’s normal behavior. Search,
counts, lists, reads, and batch mutations operate across all enabled
accounts unless the command is already inherently tied to one account
(for example mxr sync --account, mxr accounts show, or compose sender
selection).
Unknown or ambiguous selectors fail before the command is sent to the daemon. Direct-ID commands also check that the message, draft, delivery, or invite belongs to the selected account before reading or mutating it.
List the selectors currently available:
mxr accounts --format jsonCompose behavior
Section titled “Compose behavior”Compose, reply, and forward resolve the sender from the selected/default runtime account. That is the same source the TUI Accounts page shows. To send from a specific owned address rather than the account primary, use --from <address> or edit the from: frontmatter field — see Sending from an alias.
Multi-account notes
Section titled “Multi-account notes”- Sync can run per account.
- With no account chosen, the web app’s “All accounts” and the TUI list the Inbox, Starred, Sent, Drafts, Spam, Trash and All Mail of every enabled account, and their counts add up across accounts.
mxr threads --label INBOX(or SENT, DRAFT, SPAM, TRASH, STARRED) without--accountdoes the same. Name an account and you get that account’s mailbox. Starred is listed by its flag when no account has a Starred label, as on an IMAP account without a flagged folder. Your own labels are listed for every enabled account: a label that two accounts share appears once per account, each with its account’s chip and its own counts, and opening it opens that account’s label. Applying or moving a label by name uses each message’s own account’s label of that name, and refuses, naming the account, when that account has none. Categories are one list across accounts, and subscriptions count every account. A Gmail thread synced before v0.4.52 that two of your accounts both hold lists once; newer mail is kept per account. - Mail reads, searches, saved searches, reply queues, deliveries, invites, drafts, and core mutations can run per account with
--account. - The daemon tracks account health in status and diagnostics.
- Changing editable accounts in the TUI triggers daemon reload so the runtime view updates without a restart.
- Runtime-only accounts are inspectable in the TUI even when they are not editable there.