mutt-wizard

This is lael-labs/mutt-wizard, a fork of Luke Smith's mutt-wizard. The original program and most of this code are his work. This fork fixes bugs and adds options (TLS mode, authentication mechanism, folder handling) while keeping the same interface and the GPLv3 license.

What it does:

• A full-featured and autoconfigured email client on the terminal built with neomutt
• Mail stored offline enabling the ability to:
  • view and write emails while you're away from the internet
  • make backups
• Provides a mailsync script that can be scheduled to run as often as you like, which downloads/syncs mail and optionally notifies you when new mail has arrived.

Specifically, this wizard:

• Determines your email server's IMAP and SMTP servers and ports
• Creates dotfiles for neomutt, isync, and msmtp appropriate for your email address
• Encrypts and locally stores your password for easy remote access, accessible only by your GPG key
• Handles as many as nine separate email accounts automatically
• Auto-creates bindings to switch between accounts or between mailboxes
• Provides sensible defaults and an attractive appearance for the neomutt email client
• If mutt-wizard doesn't know your server's IMAP/SMTP info by default, it will prompt you for them and will put them in all the right places.

Install

Dependencies

• neomutt - the email client. (If you are using Gentoo GNU/Linux, you will need the sasl use flag to be enabled)
• curl - tests connections (required at install).
• isync - downloads and syncs the mail (required if storing IMAP mail locally).
• msmtp - sends the email.
• pass - safely encrypts passwords (required at install).
• ca-certificates - required for SSL. Probably installed already.
• gettext - writes config files. Probably installed already.

Note: There's a chance of errors if you use a slow-release distro like Ubuntu, Debian, or Mint. If you get errors in neomutt, install the most recent version manually or manually remove the offending lines in the config in /usr/share/mutt-wizard/mutt-wizard.muttrc.

git clone https://github.com/lael-labs/mutt-wizard
cd mutt-wizard
sudo make install

The Makefile also installs the zsh and fish completions. PREFIX defaults to /usr/local. Distribution packages named mutt-wizard usually build the upstream project, not this fork.

Optional Dependencies

• goimapnotify - required for push notifications. Check here for reference.
• cyrus-sasl-xoauth2 - Lets isync log in with OAuth2 (mw -A xoauth2). On Arch, cyrus-sasl-xoauth2-git from the AUR. OAuth2 also needs neomutt's mutt_oauth2.py or another token helper.
• pam-gnupg - Automatically logs you into your GPG key on login so you will never need to input your password once logged on to your system. Check the repo and directions out here.
• lynx - view HTML email in neomutt.
• notmuch - index and search mail. Install it and run notmuch setup, tell it that your mail is in ~/.local/share/mail/ (although mw will do this automatically if you haven't set notmuch up before). You can run it in mutt with ctrl-f. Run notmuch new to process new mail.
• abook - a terminal-based address book. Pressing tab while typing an address to send mail to will suggest contacts that are in your abook.
• urlview - outputs urls in mail to browser.
• cronie - (or any other major cronjob manager) to set up automatic mail syncing.
• mpop - If you want to use POP protocol instead of IMAP.

Usage

The mutt-wizard runs via the command mw. Once setup is complete, you'll use neomutt to access your mail.

• mw -a you@email.com -- add a new email account. On systemd, the first add also installs a user timer that syncs every 10 minutes (turn it off with mw -T; set MW_NO_TIMER=1 to skip it, or use -o for online-only accounts). An existing timer, launchd agent or crontab line is left alone.
• mw -l -- list existing accounts
• mw -d -- choose an account to delete
• mw -D your@email.com -- delete account settings without confirmation
• mw -t 30 -- toggle automatic mailsync to every 30 minutes
• mw -T -- toggle mailsync without specifying minutes (default is 10)
• mw -r -- reorder account shortcut numbers
• pass edit your@email.com -- revise an account's password
• mailsync -- sync all configured email accounts. Also gives notifications of new mail and indexes new mail with notmuch silently.
• mailsync your@email.com -- sync a particular (or several) email account(s).

Options usable when adding an account

Providing arguments

• -u -- Give an account username if different from the email address.
• -n -- A real name to be used by the account. Put in quotations if multiple words.
• -i -- IMAP server address
• -I -- IMAP/POP server port (otherwise taken from the domain list, then 993 for IMAP or 995 for POP)
• -s -- SMTP server address
• -S -- SMTP server port (otherwise taken from the domain list, then 465)
• -e -- IMAP/POP TLS mode: implicit, starttls or none. By default it is derived from the port (993/995 implicit, 143/110 starttls, 1143 none).
• -E -- SMTP TLS mode: implicit, starttls or none. By default it is derived from the port (465 implicit, 587/25 starttls).
• -A -- Authentication mechanism: login (default), plain, ntlm, gssapi, cram-md5 or xoauth2. xoauth2 logs in with an OAuth2 access token (Gmail, Outlook.com, Microsoft 365) and stores no password; see docs/oauth2.md.
• -m -- Maximum number of emails to be kept offline. No maximum is default functionality.
• -x -- Account password. You will be prompted for it otherwise.
• -g -- Also ask Mozilla's ISPDB (a central server) for the servers. Off by default.
• -N -- No network discovery: use only the flags, provider files and domains.csv.
• -c -- Accept discovered servers without asking. Needed in scripts (stdin not a terminal) when a server lies outside the address's domain.

General Settings

• -f -- Assume mailbox names and force account configuration without connecting online at all.
• -o -- Configure mutt for an account, but do not keep mail offline.
• -p -- Use POP protocol instead of IMAP (requires mpop installed).
• mailsync gives visual messages of new mail by default. Or, set MAILSYNC_MUTE=1 as an environmental variable if you prefer not having them. A list of addresses (MAILSYNC_MUTE="a@x.org,b@x.org") mutes only those accounts. MAILSYNC_FOLDERS=all also announces mail in folders other than INBOX (except Sent, Drafts, Trash, Junk, Spam and Archive); a list of folder names (MAILSYNC_FOLDERS="Lists/foo,Work") adds just those. MAILSYNC_MUTE_FROM ("*@news.example,noreply@*") counts but does not announce mail from matching senders. MAILSYNC_ACTION=1 adds an "Open" button to notifications that starts ${MAILSYNC_OPEN:-$TERMINAL -e neomutt} on the account. See man mailsync.

Neomutt user interface

To give you an example of the interface, here's an idea:

• m - send mail (uses your default $EDITOR to write)
• j/k and d/u - vim-like bindings to go down and up (or d/u to go down/up a page).
• l - open mail, or attachment page or attachment
• h - the opposite of l
• r/R - reply/reply all to highlighted mail
• s - save selected mail or selected attachment
• gs,gi,ga,gd,gS - Press g followed by another letter to change mailbox: sent, inbox, archive, drafts, Spam, etc.
• M and C - For Move and Copy: follow them with one of the mailbox letters above, i.e. MS means "move to Spam".
• i# - Press i followed by a number 1-9 to go to a different account. If you add 9 accounts via mutt-wizard, they will each be assigned a number.
• a to add address/person to abook and Tab while typing address to complete one from abook.
• ? - see all keyboard shortcuts
• ctrl-j/ctrl-k - move up and down in sidebar, ctrl-o opens mailbox.
• ctrl-b - open a menu to select a URL you want to open in your browser.
• p - encrypt/sign your message (in compose view, before sending the email).

Enable push notifications per mail

Note: Replace the fulladdrs with your actual email address. You have to do this for each new mail you want to setup instant notifications.

systemctl enable --user goimapnotify@fulladdrs.service

Additional functionality

• pam-gnupg - Automatically logs you into your GPG key on login, so you will never need to input your password once logged on to your system. Check the repo and directions out here.
• lynx - View HTML email in neomutt.
• notmuch - Index and search mail. Install it and run notmuch setup, tell it that your mail is in ~/.local/share/mail/ (although mw will do this automatically if you haven't set notmuch up before). You can run it in mutt with ctrl-f. Run notmuch new to process new mail.
• abook - A terminal-based address book. Pressing tab while typing an address to send mail to will suggest contacts that are in your abook.
• urlview - Outputs URLs in an email to your browser.

New stuff and improvements since the original release

• mw is now scriptable with command-line options and can run successfully without any interaction, making it possible to deploy in a script.
• isync/mbsync has replaced offlineimap as the backend. Offlineimap was error-prone, bloated, used obsolete Python 2 modules, and required separate steps to install the system.
• mw is now an installed program instead of just a script needed to be kept in your mutt folder.
• dialog is no longer used and the interface is simply text commands.
• More autogenerated shortcuts that allow quickly moving and copying mail between boxes.
• More elegant attachment handling. Image/video/pdf attachments without relying on the neomutt instance.
• abook integration by default.
• The messy template files and other directories have been moved or removed, leaving a clean config folder.
• msmtp configs moved to ~/.config/ and mail default location moved to ~/.local/share/mail/, reducing mess in ~.
• pass is used as a password manager instead of separately saving passwords.
• Error handling for the many people who don't read or follow directions. Fewer errors generally.
• Addition of a manual man mw
• Now handles POP protocol via mpop for those who prefer it (add an account with the -p option). POP configs are still generated automatically.

Help the Project!

• Try mutt-wizard out on weird machines and weird email addresses and report any errors.
• Open a pull request here to add server information to domains.csv. Until local overrides exist, you can also edit the installed copy or pass -i, -I, -s and -S.
• The original project is Luke Smith's. Support and credit for it go to him: https://github.com/lukesmithxyz/mutt-wizard.

Details for Tinkerers

• The critical mutt/neomutt files are in ~/.config/mutt/.
• Put whatever global settings you want in muttrc. mutt-wizard will add some lines to this file, which you shouldn't remove unless you know what you're doing, but you can move them up/down over your config lines if you need to. If you get binding conflict errors in mutt, you might need to do this.
• Each of the accounts that mutt-wizard generates will have custom settings set in a separate file in accounts/. You can edit these freely if you want to tinker with settings specific to an account.
• In /usr/share/mutt-wizard are several global config files, including mutt-wizard's default settings. You can override this in your muttrc if you wish.

Watch out for these things

• Gmail accounts need an App Password, which requires two-factor authentication to be on. Give the app password to mw as the account password. It is stored encrypted with pass. You might also need to enable IMAP in the Gmail settings. To skip app passwords, add the account with -A xoauth2 instead (OAuth2; you register your own client id, see docs/oauth2.md).
• If you have a university email or enterprise-hosted email for work, there might be other hurdles or two-factor authentication you have to jump through. Some, for example, will want you to create a separate IMAP password, etc.
• isync is not fully UTF-8 compatible, so non-Latin characters may be garbled (although sync should succeed). mw will also not auto-create mailbox shortcuts since it is looking for English mailbox names. I strongly recommend you to set your email language to English on your mail server to avoid these problems.

License

mutt-wizard is free/libre software. This program is released under the GPLv3 license, which you can find in the file LICENSE. Copyright remains with Luke Smith and the other upstream contributors.