Skip to content

Commit

Permalink
Merge branch 'vladdoster-patch-1'
Browse files Browse the repository at this point in the history
  • Loading branch information
@LukeSmithxyz
LukeSmithxyz committed Jan 7, 2021
2 parents 8b9f8c1 + c05b6aa commit aec0f88
Showing 1 changed file with 119 additions and 83 deletions.
202 changes: 119 additions & 83 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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 [email protected]` -- add a new email account
- `mw -l` -- list existing accounts
Expand All @@ -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
Expand All @@ -122,72 +160,70 @@ 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)

See Luke's website [here](https://lukesmith.xyz). Email him at
[[email protected]](mailto:[email protected]).

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).

0 comments on commit aec0f88

Please sign in to comment.