You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

README.md 10 KiB

6 years ago
5 years ago
5 years ago
5 years ago
6 years ago
3 years ago
5 years ago
5 years ago
3 years ago
3 years ago
3 years ago
5 years ago
5 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
5 years ago
3 years ago
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227
  1. # mutt-wizard
  2. Get this great stuff without effort:
  3. - A full-featured and autoconfigured email client on the terminal with neomutt
  4. - Mail stored offline enabling the ability to:
  5. * view and write emails while you're away from
  6. the internet
  7. * make backups
  8. - Provides a `mailsync` script that can be scheduled to run as often as you
  9. like, which downloads/syncs mail and notifies you when new mail has arrived.
  10. Specifically, this wizard:
  11. - Determines your email server's IMAP and SMTP servers and ports
  12. - Creates dotfiles for `neomutt`, `isync`, and `msmtp` appropriate for your
  13. email address
  14. - Encrypts and locally stores your password for easy remote access, accessible
  15. only by your GPG key
  16. - Handles as many as nine separate email accounts automatically
  17. - Auto-creates bindings to switch between accounts or between mailboxes
  18. - Provides sensible defaults and an attractive appearance for the neomutt email
  19. client
  20. - If mutt-wizard doesn't know your server's IMAP/SMTP info by default, it will
  21. prompt you for them and will put them in all the right places.
  22. ## Install
  23. #### Dependencies
  24. - `neomutt` - the email client.
  25. - `curl` - tests connections (required at install).
  26. - `isync` - downloads and syncs the mail (required if storing IMAP mail locally).
  27. - `msmtp` - sends the email.
  28. - `pass` - safely encrypts passwords (required at install).
  29. **Note**: There's a chance of errors if you use a slow-release distro like
  30. Ubuntu, Debian, or Mint. If you get errors in `neomutt`, install the most
  31. recent version manually or manually remove the offending lines in the config in
  32. `/usr/share/mutt-wizard/mutt-wizard.muttrc`.
  33. ```bash
  34. git clone https://github.com/LukeSmithxyz/mutt-wizard
  35. cd mutt-wizard
  36. sudo make install
  37. ```
  38. A user of Arch-based distros can also install the current mutt-wizard release from the AUR as
  39. [mutt-wizard](https://aur.archlinux.org/packages/mutt-wizard/), or the Github master branch, [mutt-wizard-git](https://aur.archlinux.org/packages/mutt-wizard-git/).
  40. ### Optional Dependencies
  41. - `pam-gnupg` - Automatically logs you into your GPG key on login so you will
  42. never need to input your password once logged on to your system. Check the
  43. repo and directions out [here](https://github.com/cruegge/pam-gnupg).
  44. - `lynx` - view HTML email in neomutt.
  45. - `notmuch` - index and search mail. Install it and run `notmuch setup`, tell
  46. it that your mail is in `~/.local/share/mail/` (although `mw` will do this
  47. automatically if you haven't set notmuch up before). You can run it in mutt
  48. with `ctrl-f`. Run `notmuch new` to process new mail.
  49. - `abook` - a terminal-based address book. Pressing tab while typing an address
  50. to send mail to will suggest contacts that are in your abook.
  51. - `urlview` - outputs urls in mail to browser.
  52. - `cronie` - (or any other major cronjob manager) to set up automatic mail
  53. syncing.
  54. - `mpop` - If you want to use POP protocol instead of IMAP.
  55. ## Usage
  56. The mutt-wizard runs via the command `mw`. Once setup is complete, you'll use
  57. `neomutt` to access your mail.
  58. - `mw -a you@email.com` -- add a new email account
  59. - `mw -l` -- list existing accounts
  60. - `mw -y your@email.com` -- sync an email account
  61. - `mw -Y` -- sync all configured email accounts
  62. - `mw -d` -- choose an account to delete
  63. - `mw -D your@email.com` -- delete account settings without confirmation
  64. - `mw -t 30` -- toggle automatic mailsync to every 30 minutes
  65. - `mw -T` -- toggle mailsync without specifying minutes (default is 10)
  66. - `pass edit mw-your@email.com` -- revise an account's password
  67. ### Options usable when adding an account
  68. #### Providing arguments
  69. - `-u` -- Give an account username if different from the email address.
  70. - `-n` -- A real name to be used by the account. Put in quotations if multiple
  71. words.
  72. - `-i` -- IMAP server address
  73. - `-I` -- IMAP server port (otherwise assumed to be 993)
  74. - `-s` -- SMTP server address
  75. - `-S` -- SMTP server port (otherwise assumed to be 587)
  76. - `-m` -- Maximum number of emails to be kept offline. No maximum is default
  77. functionality.
  78. - `-x` -- Account password. You will be prompted for it otherwise.
  79. #### General Settings
  80. - `-p` -- Add a Protonmail account.
  81. - `-f` -- Assume mailbox names and force account configuration without
  82. connecting online at all.
  83. - `-o` -- Configure mutt for an account, but do not keep mail offline.
  84. - `-P` -- Use POP protocol instead of IMAP (requires `mpop` installed).
  85. ## Neomutt user interface
  86. To give you an example of the interface, here's an idea:
  87. - `m` - send mail (uses your default `$EDITOR` to write)
  88. - `j`/`k` and `d`/`u` - vim-like bindings to go down and up (or `d`/`u` to go
  89. down/up a page).
  90. - `l` - open mail, or attachment page or attachment
  91. - `h` - the opposite of `l`
  92. - `r`/`R` - reply/reply all to highlighted mail
  93. - `s` - save selected mail or selected attachment
  94. - `gs`,`gi`,`ga`,`gd`,`gS` - Press `g` followed by another letter to change
  95. mailbox: `s`ent, `i`nbox, `a`rchive, `d`rafts, `S`pam, etc.
  96. - `M` and `C` - For `M`ove and `C`opy: follow them with one of the mailbox
  97. letters above, i.e. `MS` means "move to Spam".
  98. - `i#` - Press `i` followed by a number 1-9 to go to a different account. If you
  99. add 9 accounts via mutt-wizard, they will each be assigned a number.
  100. - `a` to add address/person to abook and `Tab` while typing address to complete
  101. one from abook.
  102. - `?` - see all keyboard shortcuts
  103. - `ctrl-j`/`ctrl-k` - move up and down in sidebar, `ctrl-o` opens mailbox.
  104. - `ctrl-b` - open a menu to select a URL you want to open in your browser.
  105. ## Additional functionality
  106. - `pam-gnupg` - Automatically logs you into your GPG key on login, so you will
  107. never need to input your password once logged on to your system. Check the
  108. repo and directions out [here](https://github.com/cruegge/pam-gnupg).
  109. - `lynx` - View HTML email in neomutt.
  110. - `notmuch` - Index and search mail. Install it and run `notmuch setup`, tell it
  111. that your mail is in `~/.local/share/mail/` (although `mw` will do this
  112. automatically if you haven't set notmuch up before). You can run it in mutt
  113. with `ctrl-f`. Run `notmuch new` to process new mail.
  114. - `abook` - A terminal-based address book. Pressing tab while typing an address
  115. to send mail to will suggest contacts that are in your abook.
  116. - `urlview` - Outputs URLs in an email to your browser.
  117. ## New stuff and improvements since the original release
  118. - `mw` is now scriptable with command-line options and can run successfully
  119. without any interaction, making it possible to deploy in a script.
  120. - `isync`/`mbsync` has replaced `offlineimap` as the backend. Offlineimap was
  121. error-prone, bloated, used obsolete Python 2 modules, and required separate
  122. steps to install the system.
  123. - `mw` is now an installed program instead of just a script needed to be kept in
  124. your mutt folder.
  125. - `dialog` is no longer used and the interface is simply text commands.
  126. - More autogenerated shortcuts that allow quickly moving and copying mail
  127. between boxes.
  128. - More elegant attachment handling. Image/video/pdf attachments without relying
  129. on the neomutt instance.
  130. - abook integration by default.
  131. - The messy template files and other directories have been moved or removed,
  132. leaving a clean config folder.
  133. - msmtp configs moved to `~/.config/` and mail default location moved to
  134. `~/.local/share/mail/`, reducing mess in `~`.
  135. - `pass` is used as a password manager instead of separately saving passwords.
  136. - Script is POSIX sh compliant.
  137. - Error handling for the many people who don't read or follow directions. Fewer
  138. errors generally.
  139. - Addition of a manual `man mw`
  140. - Now handles POP protocol via `mpop` for those who prefer it (add an account
  141. with the `-P` option). POP configs are still generated automatically.
  142. ## Help the Project!
  143. - Try mutt-wizard out on weird machines and weird email addresses and report any
  144. errors.
  145. - Open a PR to add new server information into `domains.csv` so their users can
  146. more easily use mutt-wizard.
  147. - If nothing else, [Donate!](https://paypal.me/LukeMSmith)
  148. See Luke's website [here](https://lukesmith.xyz). Email him at
  149. [luke@lukesmith.xyz](mailto:luke@lukesmith.xyz).
  150. ## Details for Tinkerers
  151. - The critical `mutt`/`neomutt` files are in `~/.config/mutt/`.
  152. - Put whatever global settings you want in `muttrc`. mutt-wizard will add some
  153. lines to this file, which you shouldn't remove unless you know what you're
  154. doing, but you can move them up/down over your config lines if you need to. If
  155. you get binding conflict errors in mutt, you might need to do this.
  156. - Each of the accounts that mutt-wizard generates will have custom settings set
  157. in a separate file in `accounts/`. You can edit these freely if you want to
  158. tinker with settings specific to an account.
  159. - In `/usr/share/mutt-wizard` are several global config files, including
  160. `mutt-wizard`'s default settings. You can override this in your `muttrc` if
  161. you wish.
  162. ## Watch out for these things
  163. - Gmail accounts need to create an
  164. [App Password](https://support.google.com/accounts/answer/185833?hl=en) to
  165. use with _**less secure**_ applications. This password is single-use (i.e.
  166. for setup) and will be stored and encrypted locally. Enabling third-party
  167. applications requires turning off two-factor authentication and this will
  168. circumvent that. You might also need to manually "Enable IMAP" in the
  169. settings.
  170. - Protonmail accounts require a "Protonmail Bridge" to access
  171. PM's IMAP and SMTP servers. Configure that before running mutt-wizard. Note
  172. that when mutt-wizard asks for a password, you should put in your
  173. [bridge password](https://protonmail.com/bridge/thunderbird#3), not your
  174. account password.
  175. - Protonmail bridge is prone to timing out. Watch out for this while adding an
  176. account. If the bridge times out, try again. It might help to
  177. [increase the timeout](https://protonmail.com/support/knowledge-base/thunderbird-connection-server-timed-error/)
  178. in your `mbsyncrc`.
  179. - If you have a university email or enterprise-hosted email for work, there
  180. might be other hurdles or two-factor authentication you have to jump through.
  181. Some, for example, will want you to create a separate IMAP password, etc.
  182. - `isync` is not fully UTF-8 compatible, so non-Latin characters may be garbled
  183. (although sync should succeed). `mw` will also not auto-create mailbox
  184. shortcuts since it is looking for English mailbox names. I strongly recommend
  185. you to set your email language to English on your mail server to avoid these
  186. problems.
  187. ## License
  188. mutt-wizard is free/libre software. This program is released under the GPLv3
  189. license, which you can find in the file [LICENSE](LICENSE).