From 3fa617cf8f2717913bba270507f38ce9ff433263 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20DOUIN?= Date: Tue, 27 Aug 2024 08:56:36 +0200 Subject: [PATCH] add readme config example for main email providers --- README.md | 288 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 265 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 6a92b8bd..64315cdb 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@

CLI to manage emails, based on email-lib

Release - Repology + Repology Matrix

@@ -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 -
- Prebuilt binary +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.* -
+*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.*
Cargo @@ -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 +
+ Proton Mail (Bridge) + + 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 = "" + + message.send.backend = "smtp" + smtp.host = "127.0.0.1" + smtp.port = 1025 + smtp.encryption = false + smtp.login = "example@proton.me" + smtp.passwd.raw = "" + ``` + + 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. +
+ +
+ Gmail + + 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.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.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 = "" + # 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 = "" + # 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. +
+ +
+ Outlook + + ```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.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.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 = "" + # 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 = "" + # 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. +
+ +
+ iCloud Mail + + 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" + ``` +
+ ## FAQ
@@ -231,7 +473,7 @@ You can also manually write your own configuration, from scratch:
- How the wizard discovers IMAP configs? + How the wizard discovers IMAP/SMTP configs? 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):