mirror of
https://github.com/soywod/himalaya.git
synced 2024-11-21 18:40:19 +00:00
add readme config example for main email providers
This commit is contained in:
Clément DOUIN
parent
cd3f5ff6a6
commit
3fa617cf8f
1 changed files with 265 additions and 23 deletions
288
README.md
288
README.md
|
|
@ -4,7 +4,7 @@
|
|||
<p>CLI to manage emails, based on <a href="https://crates.io/crates/email-lib"><code>email-lib</code></a></p>
|
||||
<p>
|
||||
<a href="https://github.com/pimalaya/himalaya/releases/latest"><img alt="Release" src="https://img.shields.io/github/v/release/pimalaya/himalaya?color=success"/></a>
|
||||
<a href="https://repology.org/project/himalaya/versions"><img alt="Repology" src="https://img.shields.io/repology/repositories/himalaya"></a>
|
||||
<a href="https://repology.org/project/himalaya/versions"><img alt="Repology" src="https://img.shields.io/repology/repositories/himalaya?color=success"></a>
|
||||
<a href="https://matrix.to/#/#pimalaya:matrix.org"><img alt="Matrix" src="https://img.shields.io/matrix/pimalaya:matrix.org?color=success&label=chat"/></a>
|
||||
</p>
|
||||
</div>
|
||||
|
|
@ -17,18 +17,17 @@ $ himalaya envelope list --account posteo --folder Archives.FOSS --page 2
|
|||
|
||||
## Features
|
||||
|
||||
- Multi-accounting
|
||||
- Interactive configuration via **wizard** (requires `wizard` feature)
|
||||
- Mailbox/folder management (**create**, **list**, **expunge**, **purge**, **delete**)
|
||||
- Envelope **listing**, **filtering** and **sorting**
|
||||
- Message composition based on `$EDITOR`
|
||||
- Message manipulation (**copy**, **move**, **delete**)
|
||||
- Multi-accounting
|
||||
- **JSON** output with `--output json`
|
||||
- Basic backends:
|
||||
- **IMAP** (requires `imap` feature)
|
||||
- **Maildir** (requires `maildir` feature)
|
||||
- **Notmuch** (requires `notmuch` feature)
|
||||
- Sending backends:
|
||||
- Default backends:
|
||||
- **SMTP** (requires `smtp` feature)
|
||||
- **Sendmail** (requires `sendmail` feature)
|
||||
- PGP encryption:
|
||||
|
|
@ -37,30 +36,27 @@ $ himalaya envelope list --account posteo --folder Archives.FOSS --page 2
|
|||
- via native implementation (requires `pgp-native` feature)
|
||||
- Global system **keyring** for managing secrets (requires `keyring` feature)
|
||||
- **OAuth 2.0** authorization (requires `oauth2` feature)
|
||||
- **JSON** output via `--output json`
|
||||
|
||||
*Himalaya CLI is written in [Rust](https://www.rust-lang.org/), and relies on [cargo features](https://doc.rust-lang.org/cargo/reference/features.html) to enable or disable functionalities.*
|
||||
|
||||
*Default features can be found in the `features` section of the [`Cargo.toml`](https://github.com/pimalaya/himalaya/blob/master/Cargo.toml#L18).*
|
||||
|
||||
## Installation [](https://repology.org/project/himalaya/versions)
|
||||
## Installation
|
||||
|
||||
<details>
|
||||
<summary>Prebuilt binary</summary>
|
||||
Himalaya CLI can be installed with a prebuilt binary:
|
||||
|
||||
Himalaya CLI can be installed with a prebuilt binary:
|
||||
```bash
|
||||
# As root:
|
||||
$ curl -sSL https://raw.githubusercontent.com/pimalaya/himalaya/master/install.sh | sudo sh
|
||||
|
||||
```bash
|
||||
# As root:
|
||||
$ curl -sSL https://raw.githubusercontent.com/pimalaya/himalaya/master/install.sh | sudo sh
|
||||
|
||||
# As a regular user:
|
||||
$ curl -sSL https://raw.githubusercontent.com/pimalaya/himalaya/master/install.sh | PREFIX=~/.local sh
|
||||
```
|
||||
# As a regular user:
|
||||
$ curl -sSL https://raw.githubusercontent.com/pimalaya/himalaya/master/install.sh | PREFIX=~/.local sh
|
||||
```
|
||||
|
||||
These commands install the latest binary from the GitHub [releases](https://github.com/pimalaya/himalaya/releases) section.
|
||||
These commands install the latest binary from the GitHub [releases](https://github.com/pimalaya/himalaya/releases) section.
|
||||
|
||||
*Binaries are built with default cargo features. If you want to enable or disable a feature, please use another installation method.*
|
||||
</details>
|
||||
*Binaries are built with [default](https://github.com/pimalaya/himalaya/blob/master/Cargo.toml#L18) cargo features. If you want to enable or disable a feature, please use another installation method.*
|
||||
|
||||
<details>
|
||||
<summary>Cargo</summary>
|
||||
|
|
@ -69,7 +65,7 @@ $ himalaya envelope list --account posteo --folder Archives.FOSS --page 2
|
|||
|
||||
```bash
|
||||
$ cargo install himalaya
|
||||
|
||||
|
||||
# With only IMAP support:
|
||||
$ cargo install himalaya --no-default-features --features imap
|
||||
```
|
||||
|
|
@ -153,7 +149,7 @@ $ himalaya envelope list --account posteo --folder Archives.FOSS --page 2
|
|||
|
||||
```bash
|
||||
$ nix-env -if https://github.com/pimalaya/himalaya/archive/master.tar.gz
|
||||
|
||||
|
||||
# or, from within the source tree checkout
|
||||
$ nix-env -if .
|
||||
```
|
||||
|
|
@ -162,10 +158,10 @@ $ himalaya envelope list --account posteo --folder Archives.FOSS --page 2
|
|||
|
||||
```bash
|
||||
$ nix profile install himalaya
|
||||
|
||||
|
||||
# or, from within the source tree checkout
|
||||
$ nix profile install
|
||||
|
||||
|
||||
# you can also run Himalaya directly without installing it:
|
||||
$ nix run himalaya
|
||||
```
|
||||
|
|
@ -209,6 +205,252 @@ You can also manually write your own configuration, from scratch:
|
|||
- Paste it in a new file `~/.config/himalaya/config.toml`
|
||||
- Edit, then comment or uncomment the options you want
|
||||
|
||||
<details>
|
||||
<summary>Proton Mail (Bridge)</summary>
|
||||
|
||||
When using Proton Bridge, emails are synchronized locally and exposed via a local IMAP/SMTP server. This implies 2 things:
|
||||
|
||||
- Id order may be reversed or shuffled, but envelopes will still be sorted by date.
|
||||
- SSL/TLS needs to be deactivated manually.
|
||||
- The password to use is the one generated by Proton Bridge, not the one from your Proton Mail account.
|
||||
|
||||
```toml
|
||||
[accounts.proton]
|
||||
email = "example@proton.me"
|
||||
|
||||
backend = "imap"
|
||||
imap.host = "127.0.0.1"
|
||||
imap.port = 1143
|
||||
imap.encryption = false
|
||||
imap.login = "example@proton.me"
|
||||
imap.passwd.raw = "<bridge-imap-p@ssw0rd>"
|
||||
|
||||
message.send.backend = "smtp"
|
||||
smtp.host = "127.0.0.1"
|
||||
smtp.port = 1025
|
||||
smtp.encryption = false
|
||||
smtp.login = "example@proton.me"
|
||||
smtp.passwd.raw = "<bridge-smtp-p@ssw0rd>"
|
||||
```
|
||||
|
||||
Keeping your password inside the configuration file is good for testing purpose, but it is not safe. You have 2 better alternatives:
|
||||
|
||||
- Save your password in any password manager that can be queried via the CLI:
|
||||
|
||||
```toml
|
||||
imap.passwd.cmd = "pass show proton"
|
||||
```
|
||||
|
||||
- Use the global keyring of your system (requires the `keyring` cargo feature):
|
||||
|
||||
```toml
|
||||
imap.passwd.keyring = "proton-example"
|
||||
```
|
||||
|
||||
Running `himalaya configure -a proton` will ask for your IMAP password, just paste the one generated previously.
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Gmail</summary>
|
||||
|
||||
Google passwords cannot be used directly. There is two ways to authenticate yourself:
|
||||
|
||||
## Using [App Passwords](https://support.google.com/mail/answer/185833)
|
||||
|
||||
This option is the simplest and the fastest. First, be sure that:
|
||||
|
||||
- IMAP is enabled
|
||||
- Two-step authentication is enabled
|
||||
- Less secure app access is enabled
|
||||
|
||||
First create a [dedicated password](https://myaccount.google.com/apppasswords) for Himalaya.
|
||||
|
||||
```toml
|
||||
[accounts.gmail]
|
||||
email = "example@gmail.com"
|
||||
|
||||
folder.alias.inbox = "INBOX"
|
||||
folder.alias.sent = "[Gmail]/Sent Mail"
|
||||
folder.alias.drafts = "[Gmail]/Drafts"
|
||||
folder.alias.trash = "[Gmail]/Trash"
|
||||
|
||||
backend = "imap"
|
||||
imap.host = "imap.gmail.com"
|
||||
imap.port = 993
|
||||
imap.login = "example@gmail.com"
|
||||
imap.passwd.cmd = "pass show gmail"
|
||||
|
||||
message.send.backend = "smtp"
|
||||
smtp.host = "smtp.gmail.com"
|
||||
smtp.port = 465
|
||||
smtp.login = "example@gmail.com"
|
||||
smtp.passwd.cmd = "pass show gmail"
|
||||
```
|
||||
|
||||
Keeping your password inside the configuration file is good for testing purpose, but it is not safe. You have 2 better alternatives:
|
||||
|
||||
- Save your password in any password manager that can be queried via the CLI:
|
||||
|
||||
```toml
|
||||
imap.passwd.cmd = "pass show gmail"
|
||||
```
|
||||
|
||||
- Use the global keyring of your system (requires the `keyring` cargo feature):
|
||||
|
||||
```toml
|
||||
imap.passwd.keyring = "gmail-example"
|
||||
```
|
||||
|
||||
Running `himalaya configure -a gmail` will ask for your IMAP password, just paste the one generated previously.
|
||||
|
||||
## Using OAuth 2.0
|
||||
|
||||
This option is the most secure but the hardest to configure. It requires the `oauth2` and `keyring` cargo features.
|
||||
|
||||
First, you need to get your OAuth 2.0 credentials by following [this guide](https://developers.google.com/identity/protocols/oauth2#1.-obtain-oauth-2.0-credentials-from-the-dynamic_data.setvar.console_name-.). Once you get your client id and your client secret, you can configure your Himalaya account this way:
|
||||
|
||||
```toml
|
||||
[accounts.gmail]
|
||||
email = "example@gmail.com"
|
||||
|
||||
folder.alias.inbox = "INBOX"
|
||||
folder.alias.sent = "[Gmail]/Sent Mail"
|
||||
folder.alias.drafts = "[Gmail]/Drafts"
|
||||
folder.alias.trash = "[Gmail]/Trash"
|
||||
|
||||
backend = "imap"
|
||||
imap.host = "imap.gmail.com"
|
||||
imap.port = 993
|
||||
imap.login = "example@gmail.com"
|
||||
imap.oauth2.client-id = "<imap-client-id>"
|
||||
imap.oauth2.auth-url = "https://accounts.google.com/o/oauth2/v2/auth"
|
||||
imap.oauth2.token-url = "https://www.googleapis.com/oauth2/v3/token"
|
||||
imap.oauth2.pkce = true
|
||||
imap.oauth2.scope = "https://mail.google.com/"
|
||||
|
||||
message.send.backend = "smtp"
|
||||
smtp.host = "smtp.gmail.com"
|
||||
smtp.port = 465
|
||||
smtp.login = "example@gmail.com"
|
||||
smtp.oauth2.client-id = "<smtp-client-id>"
|
||||
smtp.oauth2.auth-url = "https://accounts.google.com/o/oauth2/v2/auth"
|
||||
smtp.oauth2.token-url = "https://www.googleapis.com/oauth2/v3/token"
|
||||
smtp.oauth2.pkce = true
|
||||
smtp.oauth2.scope = "https://mail.google.com/"
|
||||
|
||||
# If you want your SMTP to share the same client id (and so the same access token)
|
||||
# as your IMAP config, you can add the following:
|
||||
#
|
||||
# imap.oauth2.client-id = "<client-id>"
|
||||
# imap.oauth2.client-secret.keyring = "gmail-oauth2-client-secret"
|
||||
# imap.oauth2.access-token.keyring = "gmail-oauth2-access-token"
|
||||
# imap.oauth2.refresh-token.keyring = "gmail-oauth2-refresh-token"
|
||||
#
|
||||
# imap.oauth2.client-id = "<client-id>"
|
||||
# imap.oauth2.client-secret.keyring = "gmail-oauth2-client-secret"
|
||||
# imap.oauth2.access-token.keyring = "gmail-oauth2-access-token"
|
||||
# smtp.oauth2.refresh-token.keyring = "gmail-oauth2-refresh-token"
|
||||
```
|
||||
|
||||
Running `himalaya configure -a gmail` will complete your OAuth 2.0 setup and ask for your client secret.
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Outlook</summary>
|
||||
|
||||
```toml
|
||||
[accounts.outlook]
|
||||
email = "example@outlook.com"
|
||||
|
||||
backend = "imap"
|
||||
imap.host = "outlook.office365.com"
|
||||
imap.port = 993
|
||||
imap.login = "example@outlook.com"
|
||||
imap.passwd.cmd = "pass show outlook"
|
||||
|
||||
message.send.backend = "smtp"
|
||||
smtp.host = "smtp.mail.outlook.com"
|
||||
smtp.port = 587
|
||||
smtp.encryption = "start-tls"
|
||||
smtp.login = "example@outlook.com"
|
||||
smtp.passwd.cmd = "pass show outlook"
|
||||
```
|
||||
|
||||
### Using OAuth 2.0
|
||||
|
||||
This option is the most secure but the hardest to configure. First, you need to get your OAuth 2.0 credentials by following [this guide](https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth). Once you get your client id and your client secret, you can configure your Himalaya account this way:
|
||||
|
||||
```toml
|
||||
[accounts.outlook]
|
||||
email = "example@outlook.com"
|
||||
|
||||
backend = "imap"
|
||||
imap.host = "outlook.office365.com"
|
||||
imap.port = 993
|
||||
imap.login = "example@outlook.com"
|
||||
imap.oauth2.client-id = "<imap-client-id>"
|
||||
imap.oauth2.auth-url = "https://login.microsoftonline.com/common/oauth2/v2.0/authorize"
|
||||
imap.oauth2.token-url = "https://login.microsoftonline.com/common/oauth2/v2.0/token"
|
||||
imap.oauth2.pkce = true
|
||||
imap.oauth2.scope = "https://outlook.office.com/IMAP.AccessAsUser.All"
|
||||
|
||||
message.send.backend = "smtp"
|
||||
smtp.host = "smtp.mail.outlook.com"
|
||||
smtp.port = 587
|
||||
smtp.starttls = true
|
||||
smtp.login = "example@outlook.com"
|
||||
smtp.oauth2.client-id = "<smtp-client-id>"
|
||||
smtp.oauth2.auth-url = "https://login.microsoftonline.com/common/oauth2/v2.0/authorize"
|
||||
smtp.oauth2.token-url = "https://login.microsoftonline.com/common/oauth2/v2.0/token"
|
||||
smtp.oauth2.pkce = true
|
||||
smtp.oauth2.scope = "https://outlook.office.com/SMTP.Send"
|
||||
|
||||
# If you want your SMTP to share the same client id (and so the same access token)
|
||||
# as your IMAP config, you can add the following:
|
||||
#
|
||||
# imap.oauth2.client-id = "<client-id>"
|
||||
# imap.oauth2.client-secret.keyring = "outlook-oauth2-client-secret"
|
||||
# imap.oauth2.access-token.keyring = "outlook-oauth2-access-token"
|
||||
# imap.oauth2.refresh-token.keyring = "outlook-oauth2-refresh-token"
|
||||
#
|
||||
# imap.oauth2.client-id = "<client-id>"
|
||||
# imap.oauth2.client-secret.keyring = "outlook-oauth2-client-secret"
|
||||
# imap.oauth2.access-token.keyring = "outlook-oauth2-access-token"
|
||||
# smtp.oauth2.refresh-token.keyring = "outlook-oauth2-refresh-token"
|
||||
```
|
||||
|
||||
Running `himalaya configure -a outlook` will complete your OAuth 2.0 setup and ask for your client secret.
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>iCloud Mail</summary>
|
||||
|
||||
From the [iCloud Mail](https://support.apple.com/en-us/HT202304) support page:
|
||||
|
||||
- IMAP port = `993`.
|
||||
- IMAP login = name of your iCloud Mail email address (for example, `johnappleseed`, not `johnappleseed@icloud.com`)
|
||||
- SMTP port = `587` with `STARTTLS`
|
||||
- SMTP login = full iCloud Mail email address (for example, `johnappleseed@icloud.com`, not `johnappleseed`)
|
||||
|
||||
```toml
|
||||
[accounts.icloud]
|
||||
email = "johnappleseed@icloud.com"
|
||||
|
||||
backend = "imap"
|
||||
imap.host = "imap.mail.me.com"
|
||||
imap.port = 993
|
||||
imap.login = "johnappleseed"
|
||||
imap.passwd.cmd = "pass show icloud"
|
||||
|
||||
message.send.backend = "smtp"
|
||||
smtp.host = "smtp.mail.me.com"
|
||||
smtp.port = 587
|
||||
smtp.encryption = "start-tls"
|
||||
smtp.login = "johnappleseed@icloud.com"
|
||||
smtp.passwd.cmd = "pass show icloud"
|
||||
```
|
||||
</details>
|
||||
|
||||
## FAQ
|
||||
|
||||
<details>
|
||||
|
|
@ -231,7 +473,7 @@ You can also manually write your own configuration, from scratch:
|
|||
</details>
|
||||
|
||||
<details>
|
||||
<summary>How the wizard discovers IMAP configs?</summary>
|
||||
<summary>How the wizard discovers IMAP/SMTP configs?</summary>
|
||||
|
||||
All the lookup mechanisms use the email address domain as base for the lookup. It is heavily inspired from the Thunderbird [Autoconfiguration](https://udn.realityripple.com/docs/Mozilla/Thunderbird/Autoconfiguration) protocol. For example, for the email address `test@example.com`, the lookup is performed as (in this order):
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue