diff --git a/README.md b/README.md index 7c5e926..2b1e118 100644 --- a/README.md +++ b/README.md @@ -11,32 +11,68 @@ Rationale: * Standard-compliant (we don't care about Microsoft Outlook) * Fully open-source +## How does it work? + +hydroxide is a server that translates standard protocols (SMTP, IMAP, CardDAV) +into ProtonMail API requests. It allows you to use your preferred e-mail clients +and `git-send-email` with ProtonMail. + + +-----------------+ +-------------+ ProtonMail +--------------+ + | | IMAP, SMTP | | API | | + | E-mail client <-------------> hydroxide <--------------> ProtonMail | + | | | | | | + +-----------------+ +-------------+ +--------------+ + ## Setup ### Go -hydroxide is implemented with Go. Head to [Go website](https://golang.org) -for setup information. +hydroxide is implemented in Go. Head to [Go website](https://golang.org) for +setup information. -### Install and Setup +### Installing -Install hydroxide +Start by installing hydroxide: ```shell go get github.com/emersion/hydroxide/cmd/hydroxide ``` -Your credentials will be stored on disk encrypted with a 32-byte random -password. When configuring your client, you'll need this password. +Then you'll need to login to ProtonMail via hydroxide, so that hydroxide can +retrieve e-mails from ProtonMail. You can do so with this command: ```shell hydroxide auth ``` +Once you're logged in, a "bridge password" will be printed. Don't close your +terminal yet, as this password is not stored anywhere by hydroxide and will be +needed when configuring your e-mail client. + +Your ProtonMail credentials are stored on disk encrypted with this bridge +password (a 32-byte random password generated when logging in). + ## Usage hydroxide can be used in multiple modes. +### SMTP + +To run hydroxide as an SMTP server: + +```shell +hydroxide smtp +``` + +Once the bridge is started, you can configure your e-mail client with the +following settings: + +* Hostname: `localhost` +* Port: 1025 +* Security: none +* Username: your ProtonMail username +* Password: the bridge password (not your ProtonMail password) + ### CardDAV You must setup an HTTPS reverse proxy to forward requests to `hydroxide`. @@ -55,14 +91,6 @@ For now, it only supports unencrypted local connections. hydroxide imap ``` -### SMTP - -For now, it only supports unencrypted local connections. - -```shell -hydroxide smtp -``` - ## License MIT