AutomataGet Started

ProtonMail IMAP with hydroxide: a headless bridge on Railway

Get ProtonMail IMAP access without the desktop Bridge app. Log in with hydroxide on Windows, Mac, or Linux, deploy it to Railway, and connect it to AI with self-hosted Automata.

By , Founder & CEO, Operational Intelligence Inc.

12 min read

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.

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 byProtonemersion, open source (MIT)
Runs onYour Windows, macOS, or Linux desktopAny server, or your own computer
InterfaceDesktop app, with a CLI modeCommand line only
Proton planPaid plans only, at the time of writingDoes not check your plan; Proton does not support third-party clients
LoginIn the apphydroxide auth, once, on a machine with a browser for the CAPTCHA
ProtocolsIMAP, SMTPIMAP, SMTP, CardDAV
Encryption to clientsTLS on localhostNone unless you give it a certificate
MaturitySupported productCasually 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:

  1. Your computer runs hydroxide auth once. 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.
  2. Railway runs hydroxide serve from 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.
  3. Your app connects over IMAP (port 1143) or SMTP (port 1025) 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 -e

Close 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.me

macOS

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.me

Linux

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.me

Answer the prompts

The prompts are the same on every system:

  1. Password: your Proton login password. Nothing is shown as you type.
  2. 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.
  3. 2FA TOTP code: the six-digit code from your authenticator app, if 2FA is on.
  4. Mailbox password: only asked for accounts that still use Proton's older two-password mode.
  5. 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 auth again.

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-Clipboard

macOS

The session is under ~/Library/Application Support/hydroxide:

base64 -i ~/Library/Application\ Support/hydroxide/auth.json | pbcopy

Linux

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-copy

Never 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.

Deploy on Railway

  1. Paste the base64 from step 2 into HYDROXIDE_AUTH_JSON_B64.
  2. Deploy. The template builds hydroxide from the latest Codeberg source and attaches a volume at /data.
  3. 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 :8080

The 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.

IMAPSMTP
Hostrailway-proton-mail-bridge.railway.internalrailway-proton-mail-bridge.railway.internal
Port11431025
SecurityNoneNone
UsernameYour Proton addressYour Proton address
PasswordThe bridge passwordThe 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.

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 serve

Then 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=true

Railway'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.

Add the Proton mailbox

Open your Automata, create an account, and add a connection. Choose Email (IMAP) and enter:

FieldValue
Serverrailway-proton-mail-bridge.railway.internal
Port1143
SecurityNone. 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.
UsernameYour Proton address
PasswordThe 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-draft only 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 1143 or 1025.
  • Store the bridge password in a password manager and nowhere else outside Automata. Rotating it means running hydroxide auth again, which issues a new password and a new auth.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

SymptomLikely cause and fix
[9001] For security reasons, please complete CAPTCHAYour 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 methodYour 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 WindowsYou ran auth in Git Bash. Use PowerShell or Windows Terminal.
go: go.mod requires go >= 1.26.0Your 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 logsThe 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 addressSet NUXT_ALLOW_PRIVATE_TARGETS=true on Automata's web service and redeploy.
Automata cannot establish TLSChoose None as the security, with port 1143. The bridge has no certificate.
Automata cannot resolve railway-proton-mail-bridge.railway.internalThe 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 againA 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 nothinghydroxide'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

Comments

Questions, corrections, or your own setup? Join in below. Pick any name to post.