mutt-wizard/README.md

125 lines
7.9 KiB
Markdown
Raw Normal View History

2019-02-21 16:14:17 +01:00
# mutt-wizard
2018-02-11 22:14:14 +01:00
2019-04-20 02:28:52 +02:00
Get this great stuff without effort:
2018-02-11 20:37:46 +01:00
2019-04-16 19:55:50 +02:00
- A full-featured and autoconfigured email client on the terminal with neomutt
- Mail stored offline so you can view and write email while away from internet and keep backups
Specifically, this wizard:
- Determines your email server's IMAP and SMTP servers and ports
2019-04-20 04:00:26 +02:00
- Creates dotfiles for `neomutt`, `isync`, and `msmtp` appropriate for your email address
2019-04-16 19:55:50 +02:00
- Encrypts and stores locally 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
- Can automatically set mail updates as often as you want to sync your mail and update you when new mail arrives
- Provides sensible defaults and an attractive appearance for the neomutt email client
2019-04-20 02:28:52 +02:00
- 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.
2018-02-11 20:37:46 +01:00
2019-04-16 19:55:50 +02:00
## Install and Use
2019-02-21 16:14:17 +01:00
2019-04-16 19:55:50 +02:00
```
2019-04-22 04:21:57 +02:00
git clone https://github.com/LukeSmithxyz/mutt-wizard
cd mutt-wizard
2019-04-22 03:46:59 +02:00
sudo make install
2019-04-16 19:55:50 +02:00
```
2019-02-21 16:14:17 +01:00
2019-04-23 18:46:47 +02:00
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/).
2019-04-25 19:57:14 +02:00
*NOTE:* If you have used an older version of mutt-wizard, especially when it used to use `offlineimap`, you need to remove your old configs. Back anything up that's important and run:
```
rm -rf ~/.config/mutt ~/.msmtprc ~/.config/msmtp ~/.offlineimap ~/.offlineimaprc ~/.config/offlineimap ~/.mbsyncrc
```
2019-04-22 20:21:22 +02:00
The mutt-wizard is run with the command `mw`. It also installs the `mailsync` command. Once everything is setup, you'll use `neomutt` to access your mail.
2019-04-22 04:21:57 +02:00
2019-04-22 20:21:22 +02:00
- `mw add` -- add a new email account
- `mw ls` -- list existing accounts
- `mw pass` -- revise an account's password
- `mw delete` -- deleted an added account
- `mw purge` -- delete all accounts and settings
- `mw cron` -- toggle/configure a cronjob to sync mail
## Dependencies
2019-02-21 16:14:17 +01:00
2019-04-16 19:55:50 +02:00
- `neomutt` - the email client.
2019-04-20 02:28:52 +02:00
- `isync` - downloads and syncs the mail. (required at install)
2019-04-16 19:55:50 +02:00
- `msmtp` - sends the email.
2019-04-20 02:28:52 +02:00
- `pass` - safely encrypts passwords (required at install)
2019-04-27 14:40:39 +02:00
- `urlview` - outputs urls in mail to browser.
2019-02-21 16:29:50 +01:00
2019-05-03 01:26:17 +02:00
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`.
2019-04-22 20:21:22 +02:00
### Optional
2019-02-21 16:29:50 +01:00
2019-04-16 19:55:50 +02:00
- `w3m` - view HTML email and images in neomutt.
2019-04-26 17:15:04 +02:00
- `[notmuch](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, although the included `mailsync` script does this for you.
2019-04-26 16:40:14 +02:00
- `libnotify`/`libnotify-bin` - allows notifications when syncthing mail with `mailsync`
2019-04-16 19:55:50 +02:00
- `abook` - a terminal-based address book. Pressing tab while typing an address to send mail to will suggest contacts that are in your abook.
- A cron manager - if you want to enable the auto-sync feature.
2019-04-25 17:32:48 +02:00
- `pam-gnupg` - this is a more general program that I use. It 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).
2019-02-21 16:29:50 +01:00
2019-04-22 20:21:22 +02:00
## Neomutt user interface
2019-02-21 16:14:17 +01:00
2019-04-16 19:55:50 +02:00
To give you an example of the interface, here's an idea:
2019-02-21 16:14:17 +01:00
2019-04-16 19:55:50 +02:00
- `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).
2019-04-21 13:41:07 +02:00
- `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
2019-04-16 19:55:50 +02:00
- `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.
2019-04-20 19:21:58 +02:00
- `a` to add address/person to abook and `Tab` while typing address to complete one from book.
2019-04-16 19:55:50 +02:00
- `?` - see all keyboard shortcuts
2019-04-27 14:58:36 +02:00
- `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.
2019-02-21 16:14:17 +01:00
## New stuff and improvements since the original release
2019-04-16 19:55:50 +02:00
- `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.
2019-04-22 20:21:22 +02:00
- `mw` is now an installed program instead of just a script needed to be kept in your mutt folder.
- `dialog` is no long used (le bloat) and the interface is simply text commands.
2019-02-21 16:14:17 +01:00
- 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.
2019-04-22 20:21:22 +02:00
- The messy template files and other directories have been moved or removed, leaving a clean config folder.
2019-04-20 19:21:58 +02:00
- msmtp configs moved to `~/.config/` and mail default location moved to `~/.local/share/mail/`, reducing mess in `~`.
2019-04-20 02:28:52 +02:00
- `pass` is used as a password manager instead of separately saving passwords.
2019-04-16 19:55:50 +02:00
- Script is POSIX sh compliant.
2019-04-22 20:21:22 +02:00
- Error handling for the many people who don't read or follow directions. Less errors generally.
2019-04-22 20:44:35 +02:00
- Addition of a manual `man mw`
2019-02-21 16:14:17 +01:00
2019-04-16 19:55:50 +02:00
## Help the Project!
2019-02-21 16:14:17 +01:00
- 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)
See Luke's website [here](https://lukesmith.xyz). Email him at [luke@lukesmith.xyz](mailto:luke@lukesmith.xyz).
2019-04-16 19:55:50 +02:00
mutt-wizard is free/libre software, licensed under the GPLv3.
2019-04-20 02:28:52 +02:00
## Details for Tinkerers
2019-04-22 20:21:22 +02:00
- 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.
- 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.
2019-04-22 20:23:56 +02:00
- In `/usr/share/mutt-wizard` are several global config files, including `mutt-wizard`'s default settings. You can overwride this in your `muttrc` if you wish.
2019-04-22 20:21:22 +02:00
2019-04-25 10:18:13 +02:00
## Watch out for these things:
2019-04-22 20:21:22 +02:00
2019-05-03 00:55:20 +02:00
- For Gmail accounts, remember also to enable third-party ("""less secure""") applications before attempting installation. You might also need to manually "Enable IMAP" in the settings.
2019-04-22 20:21:22 +02:00
- Protonmail accounts will require you to set up "Protonmail Bridge" to access PM's IMAP and SMTP servers. Configure that before running mutt-wizard.
- 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.
2019-05-03 00:55:20 +02:00
- `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.
2019-05-03 00:49:17 +02:00
## To-do
- Add Mac OS/BSD compatibility
- Out-of-the-box compatibility with Protonmail Bridge
- Option to ignore `domains.csv` (for troubleshooting)
- Option to keep configuration for accounts that failed to connect (maybe)