add readme config example for main email providers

pimalaya · Aug 27, 2024 · 3fa617c · 3fa617c
1 parent cd3f5ff
commit 3fa617c
Showing 1 changed file with 265 additions and 23 deletions.
diff --git a/README.md b/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 [![Repology](https://img.shields.io/repology/repositories/himalaya)](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 = "[email protected]"
+
+  backend = "imap"
+  imap.host = "127.0.0.1"
+  imap.port = 1143
+  imap.encryption = false
+  imap.login = "[email protected]"
+  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 = "[email protected]"
+  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 = "[email protected]"
+
+  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 = "[email protected]"
+  imap.passwd.cmd = "pass show gmail"
+
+  message.send.backend = "smtp"
+  smtp.host = "smtp.gmail.com"
+  smtp.port = 465
+  smtp.login = "[email protected]"
+  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 = "[email protected]"
+
+  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 = "[email protected]"
+  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 = "[email protected]"
+  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 = "[email protected]"
+
+  backend = "imap"
+  imap.host = "outlook.office365.com"
+  imap.port = 993
+  imap.login = "[email protected]"
+  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 = "[email protected]"
+  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 = "[email protected]"
+
+  backend = "imap"
+  imap.host = "outlook.office365.com"
+  imap.port = 993
+  imap.login = "[email protected]"
+  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 = "[email protected]"
+  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 `[email protected]`)
+  - SMTP port = `587` with `STARTTLS`
+  - SMTP login = full iCloud Mail email address (for example, `[email protected]`, not `johnappleseed`)
+
+  ```toml
+  [accounts.icloud]
+  email = "[email protected]"
+
+  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 = "[email protected]"
+  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 `[email protected]`, the lookup is performed as (in this order):