Luke Smith
5 years ago
No known key found for this signature in database
GPG Key ID: 4C50B54A911F6252
1 changed files with 119 additions and 83 deletions
Split View
Diff Options
-
+119 -83README.md
+ 119
- 83
README.md
View File
| @@ -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). | |||