mutt-wizard

Autoconfigure a terminal email setup with mutt and offline mail
Log | Files | Refs | README | LICENSE

commit aec0f88c13469110ba2da8325c5aa3369e7444d4
parent 8b9f8c1c384c3e148cdd832047156d2bedda517e
Author: Luke Smith <luke@lukesmith.xyz>
Date:   Thu,  7 Jan 2021 18:35:15 -0500

Merge branch 'vladdoster-patch-1'

Diffstat:
MREADME.md | 202++++++++++++++++++++++++++++++++++++++++++++++---------------------------------
1 file changed, 119 insertions(+), 83 deletions(-)

diff --git a/README.md b/README.md @@ -3,8 +3,10 @@ Get this great stuff without effort: - A full-featured and autoconfigured email client on the terminal with neomutt -- Mail stored offline so you can view and write email while you're away from - internet and keep backups +- 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 notifies you when new mail has arrived. @@ -22,17 +24,51 @@ Specifically, this wizard: - 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 and Use +## Install -``` +#### Dependencies + +- `neomutt` - the email client. +- `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). + +**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`. + +```bash git clone https://github.com/LukeSmithxyz/mutt-wizard cd mutt-wizard sudo make install ``` -User of Arch-based distros can also install mutt-wizard from the AUR as [mutt-wizard-git](https://aur.archlinux.org/packages/mutt-wizard-git/). +A user of Arch-based distros can also install mutt-wizard from the AUR as +[mutt-wizard-git](https://aur.archlinux.org/packages/mutt-wizard-git/). + +### Optional Dependencies -The mutt-wizard is run with the command `mw`. Once everything is setup, you'll use `neomutt` to access your mail. +- `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](https://github.com/cruegge/pam-gnupg). +- `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. + + +## 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 - `mw -l` -- list existing accounts @@ -49,68 +85,70 @@ The mutt-wizard is run with the command `mw`. Once everything is setup, you'll u #### 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. +- `-n` -- A real name to be used by the account. Put in quotations if multiple + words. - `-i` -- IMAP server address - `-I` -- IMAP server port (otherwise assumed to be 993) - `-s` -- SMTP server address - `-S` -- SMTP server port (otherwise assumed to be 587) -- `-m` -- Maximum number of emails to be kept offline. No maximum is default functionality. +- `-m` -- Maximum number of emails to be kept offline. No maximum is default + functionality. - `-x` -- Account password. You will be prompted for it otherwise. #### General Settings -- `-p` -- Add a Protonmail account -- `-f` -- Assume mailbox names and force account configuration without connecting online at all. +- `-p` -- Add a Protonmail account. +- `-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. -## Dependencies - -- `neomutt` - the email client. -- `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). - -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`. - -### Optional - -- `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](https://github.com/cruegge/pam-gnupg). -- `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. - ## 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). +- `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: `s`ent, `i`nbox, `a`rchive, `d`rafts, `S`pam, etc. -- `M` and `C` - For `M`ove and `C`opy: 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 book. +- `gs`,`gi`,`ga`,`gd`,`gS` - Press `g` followed by another letter to change + mailbox: `s`ent, `i`nbox, `a`rchive, `d`rafts, `S`pam, etc. +- `M` and `C` - For `M`ove and `C`opy: 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 you browser. -- +- `ctrl-b` - open a menu to select a URL you want to open in your browser. + +## 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](https://github.com/cruegge/pam-gnupg). +- `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 + 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 (le bloat) and the interface is simply text - commands. +- `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 @@ -122,14 +160,15 @@ To give you an example of the interface, here's an idea: `~/.local/share/mail/`, reducing mess in `~`. - `pass` is used as a password manager instead of separately saving passwords. - Script is POSIX sh compliant. -- Error handling for the many people who don't read or follow directions. Less +- Error handling for the many people who don't read or follow directions. Fewer errors generally. - Addition of a manual `man mw` ## Help the Project! -- Try mutt-wizard out on weird machines and weird email addresses and report - any errors. + +- Try mutt-wizard out on weird machines and weird email addresses and report any + errors. - Open a PR to add new server information into `domains.csv` so their users can more easily use mutt-wizard. - If nothing else, [Donate!](https://paypal.me/LukeMSmith) @@ -137,57 +176,54 @@ To give you an example of the interface, here's an idea: See Luke's website [here](https://lukesmith.xyz). Email him at [luke@lukesmith.xyz](mailto:luke@lukesmith.xyz). -mutt-wizard is free/libre software, licensed under the GPLv3. - ## 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 personal config lines if you - need to. If you get binding conflict errors in mutt, you might need to do - this. + 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 overwride this in your `muttrc` if + `mutt-wizard`'s default settings. You can override this in your `muttrc` if you wish. -## Watch out for these things: - -### Gmail - -Gmail accounts should require an -[application password](https://support.google.com/accounts/answer/185833) to -work unless you allow Gmail to access "less secure" applications. You may also -need to "Enable IMAP" in your Gmail settings. - -### Protonmail - -Protonmail accounts will require you to set up "Protonmail Bridge" to access -PM's IMAP and SMTP servers. Configure that before running mutt-wizard. Note -that when mutt-wizard asks for a password, you should put in your -[bridge password](https://protonmail.com/bridge/thunderbird#3), not your -account password. - -Protonmail bridge is prone to timing out. Watch out for this while adding an -account. If the bridge times out, try again. It might help to -[increase the timeout](https://protonmail.com/support/knowledge-base/thunderbird-connection-server-timed-error/) -in your `mbsyncrc`. - -### Other - -- If you have a university email, or enterprise-hosted email for work, there +## Watch out for these things + +- Gmail accounts need to create an +- [App Password](https://support.google.com/accounts/answer/185833?hl=en) to + use with _**less secure**_ applications. This password is single-use (i.e. + for setup) and will be stored and encrypted locally. Enabling third-party + applications requires turning off two-factor authentication and this will + circumvent that. You might also need to manually "Enable IMAP" in the + settings. +- Protonmail accounts require a "Protonmail Bridge" to access + PM's IMAP and SMTP servers. Configure that before running mutt-wizard. Note + that when mutt-wizard asks for a password, you should put in your + [bridge password](https://protonmail.com/bridge/thunderbird#3), not your + account password. +- Protonmail bridge is prone to timing out. Watch out for this while adding an + account. If the bridge times out, try again. It might help to + [increase the timeout](https://protonmail.com/support/knowledge-base/thunderbird-connection-server-timed-error/) + in your `mbsyncrc`. +- 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 autocreate - 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. +- `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. ## To-do -- Add ~~Mac OS~~/~~BSD~~ compatibility (the script is confirmed to work for Mac OS and FreeBSD now) -- ~~Out-of-the-box compatibility with Protonmail Bridge~~ (I believe this is done, but more bug-testing is welcome since I don't have PM) +- [x] Add Mac OS/BSD compatibility +- [x] Out-of-the-box compatibility with Protonmail Bridge (I believe this is + done, but more bug-testing is welcome since I don't have PM) + +## License + +mutt-wizard is free/libre software. This program is released under the GPLv3 +license, which you can find in the file [LICENSE](LICENSE).