IMAP / SMTP setup
IMAP and SMTP are first-party adapters in mxr, shipped alongside Gmail. Any email provider that supports IMAP and SMTP works: Fastmail, ProtonMail (with Bridge), Outlook, Yahoo, your company’s Exchange server, self-hosted Dovecot, anything.
They sync into the same local runtime and IPC surface as Gmail accounts. The daemon still speaks the internal mxr model; IMAP folder semantics are handled in the adapter.
For Gmail-over-IMAP, mxr detects Gmail’s All Mail folder (\\All, [Gmail]/All Mail, or [Google Mail]/All Mail) and uses it as the canonical sync source when available. Archived Gmail messages are just messages without INBOX; syncing All Mail prevents archived-only mail from disappearing from local search. Non-Gmail IMAP servers sync their normal folders and map archive/move operations to provider folder operations. The first sync fetches the newest INBOX mail first, 500 messages at a time, then the other folders from newest to oldest, so recent mail is searchable while older mail is still arriving.
Add an IMAP/SMTP account
Section titled “Add an IMAP/SMTP account”The shortest path is mxr accounts add. It writes the config entry, stores the password on disk in secrets.toml, and runs an authentication round-trip before saving anything:
# Interactive — prompts for host, port, username, passwordmxr accounts add imapmxr accounts add smtp
# Combined IMAP + SMTP — one call, both sidesMXR_IMAP_PASSWORD="$WORK_IMAP_PW" MXR_SMTP_PASSWORD="$WORK_SMTP_PW" \ mxr accounts add imap-smtp \ --account-name work \ --email you@example.com \ --imap-host imap.fastmail.com --imap-username you@example.com \ --smtp-host smtp.fastmail.com --smtp-username you@example.com
# Or split — useful when sync and send live on different serversMXR_IMAP_PASSWORD="$WORK_IMAP_PW" mxr accounts add imap \ --account-name work \ --imap-host imap.fastmail.com \ --imap-username you@example.com
MXR_SMTP_PASSWORD="$WORK_SMTP_PW" mxr accounts add smtp \ --account-name work \ --smtp-host smtp.fastmail.com \ --smtp-username you@example.comPasswords resolve in this order: the --imap-password / --smtp-password flag (if present and stdin is not a TTY), then the MXR_IMAP_PASSWORD / MXR_SMTP_PASSWORD environment variables, then an interactive prompt. Pass the env-var form when scripting to keep secrets out of shell history. The credential is written to <config_dir>/secrets.toml (a plaintext file at mode 0600, keyed by password_ref + username) — never to config.toml. See Where credentials live for the disk-first storage model and its tradeoff.
If a password ever goes stale (provider rotated it, you regenerated an app password), re-run mxr accounts repair work to overwrite the stored credential without touching the rest of the account config.
Manual TOML (escape hatch)
Section titled “Manual TOML (escape hatch)”You can write the config by hand if you prefer. mxr config path shows the file location. The shape is:
[accounts.work]name = "work"email = "you@example.com"
[accounts.work.sync]type = "imap"host = "imap.example.com"port = 993username = "you@example.com"password_ref = "mxr-work-imap"use_tls = true
[accounts.work.send]type = "smtp"host = "smtp.example.com"port = 587username = "you@example.com"password_ref = "mxr-work-smtp"use_tls = truepassword_ref is the service name the daemon uses to key the stored credential (paired with the username as the account). The password itself is not in config.toml — store it with the supported command, which writes it to secrets.toml:
mxr accounts repair workIf you must place the secret by hand, it goes in <config_dir>/secrets.toml
(find the dir with mxr config path) as an entry keyed by the scoped
password_ref and username, at mode 0600:
[[secret]]service = "mxr-work-imap" # the scoped password_refaccount = "you@example.com" # the usernamesecret = "your-app-password"The keychain (macOS Keychain / Linux Secret Service) is still consulted as a
fallback when a secret is absent from secrets.toml, and a keychain hit is
migrated to disk on first read — but secrets.toml is the authoritative store.
The mxr accounts add flow above is the supported path; the manual TOML shape is documented for advanced users only.
Common provider settings
Section titled “Common provider settings”| Provider | IMAP Host | IMAP Port | SMTP Host | SMTP Port |
|---|---|---|---|---|
| Fastmail | imap.fastmail.com | 993 | smtp.fastmail.com | 587 |
| Migadu | imap.migadu.com | 993 | smtp.migadu.com | 587 |
| Outlook / Office 365 | outlook.office365.com | 993 | smtp.office365.com | 587 |
| Yahoo | imap.mail.yahoo.com | 993 | smtp.mail.yahoo.com | 587 |
| ProtonMail (Bridge) | 127.0.0.1 | 1143 | 127.0.0.1 | 1025 |
| Self-hosted (Dovecot) | your-server.com | 993 | your-server.com | 587 |
Port 993 is IMAP over TLS. Port 587 is SMTP with STARTTLS. Choose the IMAP TLS mode your local bridge supports, as described below.
Local bridges and STARTTLS
Section titled “Local bridges and STARTTLS”use_tls = true on IMAP port 143 connects in plaintext, issues STARTTLS and upgrades with full certificate verification. mxr refuses to continue if the server does not advertise STARTTLS.
A bridge that listens on the loopback interface (127.0.0.0/8, ::1 or localhost) can be used without TLS with use_tls = false. mxr refuses use_tls = false for any other host, because it would send your password unencrypted. For a remote server, use port 993 or port 143 with STARTTLS.
A local server with its own self-signed certificate on an implicit-TLS port is trusted by pinning that exact certificate:
mxr accounts test work# ...# IMAP server certificate SHA-256: e51a57a240fc06f519fd775afd20ae622d7fb8bfa0cc628c612ebf78f5eaae80The reported fingerprint is unverified. Check it against the bridge’s own certificate before adding the value from your output to the account:
[accounts.work.sync]tls_cert_sha256 = "e51a57a240fc06f519fd775afd20ae622d7fb8bfa0cc628c612ebf78f5eaae80"Pass --imap-tls-cert-sha256 <hex> to mxr accounts add imap-smtp to create an account with a certificate pin. For a plaintext loopback bridge, use --imap-no-tls without a certificate pin. See the IMAP reference for how each mode verifies the server.
For SMTP, use_tls = true selects implicit TLS on port 465 and STARTTLS on
other ports, including 587. If your provider publishes port 465 instead of 587,
set the provider’s port explicitly and test the same path mxr will use to send:
[accounts.work.send]type = "smtp"host = "smtp.example.com"port = 465username = "you@example.com"password_ref = "mxr-work-smtp"use_tls = truemxr accounts test workVerify the account
Section titled “Verify the account”# Check it appears in statusmxr status
# Test connectivitymxr accounts test work
# Trigger a syncmxr sync --account workMultiple accounts
Section titled “Multiple accounts”Add as many accounts as you need — each mxr accounts add invocation appends a new entry to the config:
MXR_IMAP_PASSWORD="$PERSONAL_IMAP_PW" mxr accounts add imap \ --account-name personal \ --imap-host imap.fastmail.com \ --imap-username me@fastmail.comMXR_SMTP_PASSWORD="$PERSONAL_SMTP_PW" mxr accounts add smtp \ --account-name personal \ --smtp-host smtp.fastmail.com \ --smtp-username me@fastmail.comYou can mix and match: one account on Gmail, another on IMAP/SMTP, a third on something else. They all sync into the same local database and are searchable together.
TUI account view
Section titled “TUI account view”Manage accounts from the TUI:
gC, or:then Settings
IMAP/SMTP accounts are fully config-backed and editable through the Accounts page.
App passwords
Section titled “App passwords”Some providers require app-specific passwords instead of your regular password when IMAP access is enabled:
- Fastmail: Settings > Privacy & Security > App Passwords
- Yahoo: Account Security > Generate app password
- Outlook with 2FA: Security > App passwords
Use the app password when mxr accounts add prompts for one — never your login password.