.TH MAILSYNC 1 .SH NAME mailsync \- sync mail accounts set up with .B mw. .SH SYNOPSIS .B mailsync [ .I OPTIONS ]... [ .I ACCOUNTS ] .SH DESCRIPTION .B mailsync syncs the mail of all accounts set up with .B mw, or if account names are given, syncs only those accounts. .B mailsync is a wrapper for .B mbsync and .B mpop, but also automatically reindexes new mail with .B notmuch, gives notifications if new mail is found and can also be run on a schedule (see .B mw -t in .BR mw (1)) to sync and index mail quietly in the background. .SH COMMANDS .TP .B mailsync sync all mail accounts and notify user if there is new mail .TP .B mailsync account@example.org only sync the .B account@example.org account. .SH CONFIGURATION While .B mailsync gives notifications on the arrival of new mail by default, this can be disabled by setting the variable .I MAILSYNC_MUTE=1. A space or comma separated list of account addresses mutes only those accounts. .SS Folders By default only new mail in the INBOX is counted and announced. Server-side filters often deliver elsewhere, so .I MAILSYNC_FOLDERS widens the search. Unset or empty means INBOX only. .B all means every folder except those named Sent, Drafts, Trash, Junk, Spam or Archive (also Bin, Sent Mail, Sent Items, Deleted Items, Junk E-mail, All Mail and similar), matched case-insensitively against every part of the folder path, so .I [Gmail]/Sent Mail and .I INBOX.Sent are both skipped whatever the server's delimiter. Anything else is a list of folder names (paths below the account's maildir, case-insensitive, "/" and "." taken as the same delimiter) to scan besides INBOX, for example .IR MAILSYNC_FOLDERS="Lists/foo,Work" . Separate names with commas, or with spaces when there is no comma; a name that contains a space needs a comma in the list (a trailing one will do). Naming a folder such as Sent explicitly scans it. .SS Muting senders .I MAILSYNC_MUTE_FROM is a space or comma separated list of address patterns (shell globs, matched case-insensitively against the address in the From header, for example .IR "*@news.example,noreply@*" ). Mail from a matching sender is still counted and indexed, and reported on standard output, but never announced; it does not count toward the five-mail limit above which one summary notification replaces the per-mail ones. .SS Notification action With .I MAILSYNC_ACTION=1 each notification carries an "Open" button. Clicking it runs .IR "${MAILSYNC_OPEN:-$TERMINAL -e neomutt}" with the neomutt options .B -e "source " and .B -f appended (the spool mailbox for a summary notification), and with the account address in .IR MAILSYNC_ACCOUNT . If neither MAILSYNC_OPEN nor TERMINAL is set, or the installed .B notify-send does not support .BR --action , plain notifications are sent without a word. Because .B notify-send --action waits until the notification is closed, each one runs in the background, so a slow or ignored notification never delays the sync. It has no effect on macOS. .SS Environment file Scheduled runs (systemd, launchd, cron) do not inherit your session environment. So .B mailsync reads one file, .IR $XDG_CONFIG_HOME/mutt-wizard/env , by default .IR ~/.config/mutt-wizard/env . .B mw writes it when an account is added and when a schedule is toggled with .B -t or .BR -T , from the variables set in its own environment, with mode 600. It is never evaluated or sourced. Each line is .IR KEY=VALUE . Only these keys are accepted: MBSYNCRC, MPOPRC, PASSWORD_STORE_DIR, PASSWORD_STORE_GPG_OPTS, NOTMUCH_CONFIG, GNUPGHOME, MAILSYNC_MUTE, MAILSYNC_FOLDERS, MAILSYNC_MUTE_FROM, MAILSYNC_ACTION, MAILSYNC_OPEN, XDG_CONFIG_HOME and XDG_DATA_HOME. Blank lines and lines starting with # are ignored, one level of matching single or double quotes around a value is removed, and .B $ and backticks in values are taken literally. A variable that is already set in the environment is not overridden. The file is also usable as a systemd .B EnvironmentFile= (no .BR export ). The file is looked up under the XDG_CONFIG_HOME of the run's own environment, or under .I ~/.config if that is unset; an XDG_CONFIG_HOME line inside the file cannot move the file itself. .PP Older versions searched shell startup files such as .I ~/.zshrc for these variables and evaluated them. That no longer happens; put the settings in the env file instead. .SS Password store check When not run from a terminal, .B mailsync first checks that the GPG key of the password store (the first line of .IR $PASSWORD_STORE_DIR/.gpg-id ) is unlocked, and stops with a message on standard error if it is not. The check is skipped when no account in the mbsync, mpop or msmtp configuration fetches its password with .BR pass . .SS Proton Bridge accounts An account whose .B IMAPStore block in the mbsync configuration has .B Host 127.0.0.1 (or localhost) and .B Port 1143 is taken to be a Proton Bridge account. Before syncing it, .B mailsync makes two checks. A failed check skips that account only; the other accounts sync as usual, and the skipped account counts as a failed sync for the exit status. .PP 1. Is Bridge running? A TCP connection to the Bridge port must succeed within 3 seconds. It is made with .B nc -z when .B nc is installed, else with .BR bash 's /dev/tcp, so no new dependency is needed; if neither exists the check is skipped and the sync goes ahead. If Bridge is not listening, .B mailsync prints "Proton Bridge is not running (127.0.0.1:1143)" followed, on systems with .BR systemctl , by "Start it with: systemctl --user start protonmail-bridge" (elsewhere by a plain request to start Bridge), and sends one notification. The check needs no systemd; without Bridge the sync is skipped at once instead of hanging. .PP 2. Is it still the certificate you pinned? If a pin exists for the account at .IR ${XDG_DATA_HOME:-~/.local/share}/mutt-wizard/certs/
.pem , .B mailsync runs .B mutt-wizard-pin check (see .IR docs/cert-pinning.md ) against Bridge's STARTTLS IMAP port. If the certificate differs (Bridge was reset, reinstalled or its vault lost), the account is skipped with "Proton Bridge certificate changed. If you reset or reinstalled Bridge, run: mw repin
", and one notification says the same. A helper status of 2 (no certificate came back) is reported like a stopped Bridge. Any other helper failure only prints a warning and the sync continues. Without a pin file no certificate check is made. The pin is never replaced by .BR mailsync . .PP Each notification is sent at most once per account and problem every 6 hours. The record is an empty file named .I bridge-down-
or .I bridge-cert-
in .IR ${XDG_STATE_HOME:-~/.local/state}/mutt-wizard/ ; deleting it allows the next run to notify again. The message on standard error is printed on every run. MAILSYNC_MUTE silences the "not running" notification; the certificate warning is never muted. .PP For tests and unusual setups, .I MAILSYNC_BRIDGE_PORT replaces 1143 as the port that is checked (an account is still recognized by the port in the mbsync file), and .I MW_PIN names the pin helper instead of the installed .IR $prefix/lib/mutt-wizard/mutt-wizard-pin . .SH AUTHORS Written by Luke Smith originally in 2018. .SH LICENSE GPLv3 .SH SEE ALSO .BR mw (1), .BR neomutt (1), .BR neomuttrc (1) .BR mbsync (1), .BR mpop (1), .BR msmtp (1), .BR notmuch (1), .BR abook (1)