hydroxide

hydroxide is a third-party, open-source ProtonMail bridge designed for power users to run on servers. It acts as a translation server that converts standard protocols (SMTP, IMAP, and CardDAV) into ProtonMail API requests. This allows you to use standard email clients and tools like git-send-email with your ProtonMail account.

Architecture Model: E-mail client <--(IMAP, SMTP)--> hydroxide <--(ProtonMail API)--> ProtonMail

To use hydroxide for CardDAV, run the carddav command.

Requirement: You must set up an HTTPS reverse proxy to forward requests to the hydroxide service. This setup has been tested with GNOME (Evolution) and Android (DAVDroid).

hydroxide carddav

Instead of starting multiple individual protocol servers, you can use the serve command to run hydroxide in a mode that handles multiple protocols.

Note: Running hydroxide serve requires the following ports to be available:

• 1025 (SMTP)
• 1143 (IMAP)
• 8080 (CardDAV)

To use hydroxide for IMAP, run the imap command.

⚠️ Warning: IMAP support is currently work-in-progress. At this time, it only supports unencrypted local connections.

hydroxide imap

hydroxide is implemented in Go. To install it, clone the repository and build the binary using the go build command targeting the cmd/hydroxide directory.

git clone https://github.com/emersion/hydroxide.git
go build ./cmd/hydroxide

Before using the bridge, you must authenticate with ProtonMail so hydroxide can retrieve your emails. Use the auth command followed by your ProtonMail username.

Important: After authentication, hydroxide will print a bridge password. This password is a 32-byte random string used to encrypt your credentials on disk. It is not stored by hydroxide, so you must copy it immediately; you will need it to configure your email client.

hydroxide auth <username>

To use hydroxide as an SMTP server, run the smtp command. Use the following settings in your email client:

• Hostname: localhost
• Port: 1025
• Security: none
• Username: Your ProtonMail username
• Password: The bridge password generated during the auth step (not your ProtonMail password)

hydroxide smtp

To log in to a ProtonMail account and set up the local bridge, use the auth command. This process will prompt you for your login password and mailbox password. If Two-Factor Authentication (TOTP) is enabled, you will be prompted for a TOTP code.

After successful authentication, hydroxide generates a Bridge password. You will need this password for subsequent commands like export-messages or import-messages.

hydroxide auth <username>

The import-messages command imports messages into a ProtonMail account. It supports importing from a file or from standard input (stdin). It can detect and process MBOX files automatically.

Usage:

# Import from a file
hydroxide import-messages <username> /path/to/archive.mbox

# Import from stdin
cat archive.mbox | hydroxide import-messages <username>

hydroxide import-messages <username> [file]

The export-messages command allows you to export ProtonMail messages into MBOX format. You can export an entire conversation or a specific message using the following flags:

• -conversation-id <id>: Export all messages in a specific conversation.
• -message-id <id>: Export a specific message.

Note: You will be prompted for the Bridge password unless HYDROXIDE_BRIDGE_PASS is set.