Proton Mail encrypts your mailbox end to end, so there is no IMAP server at Proton to point a mail client at. The official way to get ProtonMail IMAP access is Proton Mail Bridge, a desktop app that decrypts your mail locally and serves it over IMAP and SMTP on your own computer. It works well, but it has to stay open on a computer that stays on, and it needs a paid Proton plan.
hydroxide is the open-source alternative: a headless ProtonMail bridge with no GUI, written to run on a server. This guide shows how to log in with hydroxide on Windows, macOS, or Linux, deploy it to Railway with a one-click template, and then connect your Proton mailbox to Claude or another AI client through a self-hosted Automata, with the bridge and Automata on the same private network.
hydroxide is a third-party project by emersion, released under the MIT License. Neither hydroxide, the Railway template, nor Automata is affiliated with or endorsed by Proton AG.
Proton Mail Bridge or hydroxide?
Both are bridges: they log in to Proton's API, decrypt your mail with your keys, and speak standard IMAP and SMTP to whatever connects to them. The difference is where they are meant to run.
| Proton Mail Bridge (official) | hydroxide | |
|---|---|---|
| Made by | Proton | emersion, open source (MIT) |
| Runs on | Your Windows, macOS, or Linux desktop | Any server, or your own computer |
| Interface | Desktop app, with a CLI mode | Command line only |
| Proton plan | Paid plans only, at the time of writing | Does not check your plan; Proton does not support third-party clients |
| Login | In the app | hydroxide auth, once, on a machine with a browser for the CAPTCHA |
| Protocols | IMAP, SMTP | IMAP, SMTP, CardDAV |
| Encryption to clients | TLS on localhost | None unless you give it a certificate |
| Maturity | Supported product | Casually maintained; its README calls IMAP support work in progress |
Use the official Bridge if you want Proton mail in Thunderbird, Apple Mail, or Outlook on the computer in front of you. Use hydroxide when something that is not your desktop needs IMAP: a script, an automation, or an AI agent running in the cloud, available while your laptop is closed.
How it works
Three pieces are involved:
- Your computer runs
hydroxide authonce. Proton needs an interactive login and usually a CAPTCHA, which a server cannot solve, so this part happens where you have a browser. It produces a session file,auth.json, and a random bridge password. - Railway runs
hydroxide servefrom the railway-proton-mail-bridge repo. The template seeds the session file into a persistent volume, and hydroxide refreshes Proton's tokens there from then on. - Your app connects over IMAP (port
1143) or SMTP (port1025) on Railway's private network, logging in with your Proton address and the bridge password. In this guide that app is Automata, which gives an AI client scoped, read-only access to the mailbox.
auth.json holds your Proton session and passwords encrypted with the bridge password. Either one alone is useless; together they are your mailbox. Keep them in different places.
What you need
- A Proton Mail account. If two-factor authentication is on, it must use an authenticator app (TOTP); hydroxide does not support security keys.
- A Windows, macOS, or Linux computer for a one-time login, with Go 1.26 or later and Git.
- A Railway account. The bridge is one small service with a volume.
- For the AI part: a self-hosted Automata on Railway, set up in step 5.
- About 20 minutes.
Step 1: Log in to Proton with hydroxide
Build hydroxide from its Codeberg source. The older copy on the GitHub mirror, which go install github.com/emersion/hydroxide/... fetches, cannot complete Proton's CAPTCHA and fails with [9001] For security reasons, please complete CAPTCHA.
Windows
Open PowerShell or Windows Terminal. Do not use Git Bash: hydroxide reads your password from the console, which Git Bash's terminal does not provide.
winget install --id GoLang.Go -e
winget install --id Git.Git -eClose and reopen PowerShell so go and git are on your PATH, then build and log in:
git clone https://codeberg.org/emersion/hydroxide.git
cd hydroxide
go build -o hydroxide.exe ./cmd/hydroxide
.\hydroxide.exe auth you@proton.memacOS
With Homebrew, or use the installer from go.dev/dl:
brew install go git
git clone https://codeberg.org/emersion/hydroxide.git
cd hydroxide && go build ./cmd/hydroxide
./hydroxide auth you@proton.meLinux
Check go version first. Many distributions ship a Go older than 1.26. Go 1.21 and later usually download the newer toolchain by themselves, but some distributions turn that off; if the build stops with go: go.mod requires go >= 1.26.0, install the official tarball from go.dev/dl.
go version # needs go1.26 or later
git clone https://codeberg.org/emersion/hydroxide.git
cd hydroxide && go build ./cmd/hydroxide
./hydroxide auth you@proton.meAnswer the prompts
The prompts are the same on every system:
- Password: your Proton login password. Nothing is shown as you type.
- Human verification: if hydroxide prints a
https://verify.proton.me/...link, open it in a browser, complete the CAPTCHA, then go back to the terminal and press Enter. - 2FA TOTP code: the six-digit code from your authenticator app, if 2FA is on.
- Mailbox password: only asked for accounts that still use Proton's older two-password mode.
- Bridge password: hydroxide prints it on the last line. Copy it into your password manager now. hydroxide does not store it and cannot show it again; if you lose it, run
authagain.
Anyone with the bridge password and network access to the bridge can read and send mail as you. Treat it like your Proton password.
Step 2: Encode the session file
Railway variables are text, so the template takes auth.json as one line of base64. Each command below copies the result to your clipboard.
Windows
hydroxide saves the session under %AppData%\hydroxide:
[Convert]::ToBase64String([IO.File]::ReadAllBytes("$env:APPDATA\hydroxide\auth.json")) | Set-ClipboardmacOS
The session is under ~/Library/Application Support/hydroxide:
base64 -i ~/Library/Application\ Support/hydroxide/auth.json | pbcopyLinux
The session is under ~/.config/hydroxide (or $XDG_CONFIG_HOME/hydroxide). Pipe to wl-copy on Wayland or xclip -selection clipboard on X11:
base64 -w0 ~/.config/hydroxide/auth.json | wl-copyNever commit auth.json or its base64 to a repository, and do not paste it into a chat with an AI. Once the bridge is deployed you can delete the local copy, or keep it to redeploy without logging in again.
Step 3: Deploy the bridge on Railway
Click the Deploy on Railway button below, or open the Proton Mail Bridge template.
Railway's private network is per project and environment, so the bridge must live in the same project as whatever reads from it. If you already run Automata on Railway, open that project, click + New, choose Template, and search for Proton Mail Bridge. If not, deploy Automata first as described in step 5 and add the bridge to that project.
- Paste the base64 from step 2 into
HYDROXIDE_AUTH_JSON_B64. - Deploy. The template builds hydroxide from the latest Codeberg source and attaches a volume at
/data. - Keep the service at one replica. Two copies of the bridge would fight over the same Proton session.
The bridge is ready when the deploy logs show:
Seeded /data/hydroxide/auth.json from HYDROXIDE_AUTH_JSON_B64
SMTP server listening on :1025
IMAP server listening on :1143
CardDAV server listening on :8080The variable is read only on the first boot. After that, hydroxide refreshes Proton's tokens itself and saves them to the volume, so redeploys keep the session.
Step 4: Connect over the private network
Any service in the same Railway project reaches the bridge with these settings. The template names the service railway-proton-mail-bridge; if you renamed it, use the private domain shown under the service's Settings → Networking.
| IMAP | SMTP | |
|---|---|---|
| Host | railway-proton-mail-bridge.railway.internal | railway-proton-mail-bridge.railway.internal |
| Port | 1143 | 1025 |
| Security | None | None |
| Username | Your Proton address | Your Proton address |
| Password | The bridge password | The bridge password |
The template does not give hydroxide a TLS certificate, so the bridge speaks plain IMAP and SMTP. Inside a Railway project that is acceptable: Railway carries traffic between services over encrypted WireGuard tunnels and never exposes it to the internet. Choosing SSL/TLS or STARTTLS in a client will fail, because the bridge offers neither.
A Railway TCP proxy would publish the bridge to the internet without encryption. Your Proton address, the bridge password, and every email you read would cross the network in clear, and the bridge password gives full access to your mailbox. Keep IMAP and SMTP on the private network.
What about Thunderbird or Apple Mail on my computer?
A desktop mail client is not on Railway's private network, so it cannot use this deployment safely. For a client on your own computer, run a bridge locally instead: the official Proton Mail Bridge, or hydroxide itself. hydroxide serve listens on 127.0.0.1 by default, so plain IMAP never leaves your machine:
./hydroxide serve # Windows: .\hydroxide.exe serveThen point the client at 127.0.0.1, port 1143 (IMAP) and 1025 (SMTP), security None, with your Proton address and the bridge password.
Step 5: Connect Proton Mail to AI with self-hosted Automata
Automata is a free, open-source MCP server that gives AI clients such as Claude, ChatGPT, and Cursor scoped access to an IMAP mailbox: they can list, search, and read your mail, and optionally save drafts, but never send, delete, or move anything. Pointed at the bridge, it turns your Proton inbox into something an AI assistant can work with.
Why self-host both
For Proton, run Automata yourself, in the same Railway project as the bridge. This is the setup we recommend, for three reasons:
- Nothing is exposed. Automata reaches the bridge at
railway-proton-mail-bridge.railway.internal, over the encrypted private network. Hosted Automata at mcp.getautomata.app is outside your project, so it could only reach the bridge through a public TCP proxy, which is exactly what the warning above rules out. - Your secrets stay in one place you control. Automata stores each connection's password in its own database. Self-hosted, the bridge password, the Proton session, and Automata's index of your mail headers all live in your Railway project, and no one else operates any of them.
- It keeps the point of Proton. You chose Proton to keep your mail private. A self-hosted pair adds no new company to the list of those holding your mail or credentials. The one that remains is the AI provider, which receives whatever the assistant reads, so scope the token carefully.
Deploy Automata on Railway
Deploy Automata with its Railway template. An email-only deployment needs just Postgres and the web service; WhatsApp and Telegram services are optional. The Railway deployment docs cover the variables. Then add the Proton Mail Bridge to the same project with + New → Template, as in step 3.
On the Automata web service, set one more variable:
NUXT_ALLOW_PRIVATE_TARGETS=trueRailway's private addresses are IPv6 unique-local addresses, and Automata refuses private addresses by default so that users of a shared deployment cannot reach your internal network. This variable lifts that guard for the whole deployment. Automata still refuses its own Postgres and other backends whatever it says.
With private targets allowed, anyone who can create an account on your Automata could point a connection at other services in the project. Self-hosted Automata is invite-only by default: the first account becomes the administrator and everyone else needs an invitation. Leave it that way, and do not set NUXT_SIGNUP=open on this deployment.
Add the Proton mailbox
Open your Automata, create an account, and add a connection. Choose Email (IMAP) and enter:
| Field | Value |
|---|---|
| Server | railway-proton-mail-bridge.railway.internal |
| Port | 1143 |
| Security | None. Automata shows a warning that the password crosses the network unencrypted. Here it travels only inside Railway's encrypted private network, which is what that option is for. |
| Username | Your Proton address |
| Password | The bridge password from step 1 |
Automata logs in before it saves anything, so a wrong password or host fails right away. It then syncs mail headers every two minutes, backfilling the last 365 days, newest first. Bodies and attachments are not stored; they are fetched from the bridge when the AI asks for one.
hydroxide shows Proton's system folders as IMAP folders: INBOX, Archive, Sent, Drafts, Starred, Spam, Trash, and All Mail, plus your own folders and labels. Automata skips All Mail, Spam, and Trash when syncing. An email that is also in Starred or under a label is listed once, with every folder it is in.
Create a scoped token
On the connection's page, create a connector token. Start narrow:
- Folders: pick only what the assistant needs, such as INBOX and one project folder. Leave out folders with password resets, banking, and legal mail.
- Actions: keep the read-only default. Tick
create-email-draftonly if you want the assistant to save drafts, and include Drafts in the folders if you do. A draft saved through hydroxide appears in Proton's Drafts on every device. - Expiry: 30 or 90 days rather than never.
Automata shows the token once. The folder and action limits are enforced on every request in Automata, not in the prompt, so the assistant cannot talk its way past them. See permissions for the details.
Add it to Claude
The connector URL looks like this:
https://<your-automata-domain>/mcp/<connector-token>In Claude.ai or Claude Desktop, open Settings → Customize → Connectors, click Add, choose Add custom connector, name it Proton Mail, and paste the URL. In Claude Code, run:
claude mcp add --transport http proton-mail \
https://<your-automata-domain>/mcp/<connector-token>For ChatGPT, follow how to add a custom MCP server to ChatGPT. The MCP clients docs cover Cursor and others, including the Authorization: Bearer header form that keeps the token out of URLs.
Test it
In a new chat with the connector enabled, ask:
Check the mailbox status.
The assistant should report your Proton address, when the last sync ran, and which folders are still backfilling. Then try real work:
- Summarize the unread emails in my inbox from this week and list what each person is waiting on.
- Find the invoice from our hosting provider in the last two months and tell me the total.
- Draft a reply to the latest email from Sam confirming Thursday. Save it as a draft, do not send it.
Keep it safe
- Keep IMAP and SMTP private. No TCP proxy, no public domain on ports
1143or1025. - Store the bridge password in a password manager and nowhere else outside Automata. Rotating it means running
hydroxide authagain, which issues a new password and a newauth.json. - Scope tokens to folders and keep them read-only. Anyone can email you, so anyone can put instructions in front of the AI. That is prompt injection, and the defense is a token that cannot do much harm when the model is fooled. Automata cannot send mail at all; only the bridge's SMTP port can, and Automata never uses it.
- Treat the connector URL like a password. If it leaks, revoke that token in Automata; other tokens keep working.
- Remember where the text goes. Proton's end-to-end encryption protects mail at rest with Proton. Whatever the assistant reads is decrypted by the bridge and sent to your AI provider as part of the conversation.
- To shut it all off, revoke the connector tokens, delete the bridge service and its volume, and sign out the hydroxide session from Proton's security settings, or change your Proton password, which ends every session.
Troubleshooting
| Symptom | Likely cause and fix |
|---|---|
[9001] For security reasons, please complete CAPTCHA | Your hydroxide build predates CAPTCHA support. Build from the Codeberg source as in step 1, not with go install from GitHub. |
Only TOTP is supported as a 2FA method | Your Proton account uses a security key for 2FA. Add an authenticator app as a 2FA method in Proton's security settings. |
open /dev/tty error on Windows | You ran auth in Git Bash. Use PowerShell or Windows Terminal. |
go: go.mod requires go >= 1.26.0 | Your Go is too old and cannot fetch a newer toolchain. Install the latest from go.dev/dl. |
No auth.json: set HYDROXIDE_AUTH_JSON_B64 in the Railway logs | The variable is empty and the volume has no session. Set the variable and check that the volume is mounted at /data. |
Automata says the host resolves to ... a private or loopback address | Set NUXT_ALLOW_PRIVATE_TARGETS=true on Automata's web service and redeploy. |
| Automata cannot establish TLS | Choose None as the security, with port 1143. The bridge has no certificate. |
Automata cannot resolve railway-proton-mail-bridge.railway.internal | The bridge is in a different Railway project or environment, or the service was renamed. Deploy it into Automata's project and copy its private domain from Settings → Networking. |
Login refused after running auth again | A new auth issues a new bridge password that matches only the new auth.json. Update HYDROXIDE_AUTH_JSON_B64, deploy once with HYDROXIDE_AUTH_FORCE=1, remove that variable, and use Change credentials in Automata. |
| Body text search finds nothing | hydroxide's own IMAP search does not reliably search inside message bodies. Search by sender, recipient, or subject, which Automata answers from its synced headers. |
Frequently asked questions
Does Proton Mail support IMAP?
Not directly. Proton encrypts your mailbox end to end, so its servers cannot serve plain IMAP. You get IMAP through a bridge that runs on a machine you control and decrypts mail there: the official Proton Mail Bridge desktop app, or an open-source bridge such as hydroxide.
What is hydroxide?
hydroxide is a third-party, open-source ProtonMail bridge written in Go. It translates IMAP, SMTP, and CardDAV into Proton API requests, has no graphical interface, and is designed to run on a server. It is MIT licensed and not affiliated with Proton.
Is hydroxide the same as Proton Mail Bridge?
No. Proton Mail Bridge is Proton's official desktop app for Windows, macOS, and Linux, and needs a paid plan. hydroxide is an independent, headless reimplementation. Both give you IMAP and SMTP; hydroxide also serves CardDAV and runs where no desktop is available.
Does hydroxide work with a free Proton account?
hydroxide does not check your plan. Proton does not support third-party clients, though, and can change what its API allows at any time, so test with your own account before relying on it.
Why can't I log in to hydroxide on Railway directly?
Proton's login needs your password, often a CAPTCHA in a browser, and a 2FA code. That is why you run hydroxide auth once on your own computer and hand the server the encrypted session file instead.
Is plain IMAP between Automata and the bridge safe?
Inside one Railway project, yes. Railway encrypts traffic between services with WireGuard and does not expose the private network to the internet. It is not safe across the internet, which is why the bridge should never be published through a TCP proxy without TLS.
Can I use hosted Automata instead of self-hosting?
Not safely with this template. Hosted Automata runs outside your Railway project, so it could reach the bridge only over the public internet, and the bridge has no TLS. Self-host Automata next to the bridge.
Can the AI send email from my Proton account?
Not through Automata. Its email connection can read, search, and save drafts, but has no SMTP access and cannot send, delete, or move mail. You review a draft in Proton and send it yourself.
What happens when Proton's session expires?
hydroxide refreshes its tokens on its own and saves them to the volume. If Proton ends the session, for example because you changed your password or signed out all sessions, run hydroxide auth again and redeploy with the new auth.json and HYDROXIDE_AUTH_FORCE=1.
Next steps
- Star or fork the template repo: ju-li/railway-proton-mail-bridge.
- Read the email (IMAP) docs for sync behavior, limits, and every setting.
- Learn more about self-hosting Automata and its security model.
- Connect other mailboxes the same way: connect Claude to email covers Fastmail, Zoho, iCloud, and more.
- Add your chats to the same assistant with WhatsApp and Claude.
Comments
Questions, corrections, or your own setup? Join in below. Pick any name to post.