Proton Mail Bridge: Local IMAP and SMTP Setup Guide
Proton Mail Bridge application
At a glance
- What is it?
- Proton Mail Bridge exposes a Proton Mail account through local IMAP and SMTP servers for desktop email clients. It suits users whose preferred client cannot authenticate directly with Proton Mail, but requires a supported credential store and a running Bridge process for synchronization.
- Who is it for?
- Proton Mail Bridge is appropriate for Proton Mail subscribers who need standard IMAP and SMTP access in a desktop client and can keep Bridge running on the same machine. It is a poor fit for headless systems, unattended external access, or Linux users without a supported secret service.
- Can I use it commercially?
- Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
- Is it still maintained?
- Yes. The repository last received commits 24 days ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on October 22, 2026, and from our analysis. They are not legal advice.
Editorial analysis
Why Proton Mail Bridge sits between the mail client and Proton
Proton Mail Bridge solves a narrow compatibility problem: connecting a conventional desktop email client to a Proton Mail account through local IMAP and SMTP endpoints. It is intended for users who want to work in a separate mail application while keeping their mail hosted by Proton Mail. The application does not itself replace the email client. Instead, it provides the local services that the client can understand.
The documented flow begins when Bridge starts its local IMAP and SMTP servers and opens its graphical interface. The user signs in to Proton Mail there, then adds a Proton account to an email client using the settings displayed by Bridge. Those settings include connection information that must remain aligned with the running Bridge instance. This arrangement gives desktop clients a familiar protocol boundary without requiring the client itself to understand Proton's account authentication.
The arrangement has an important operational consequence. The README states that the client can synchronize only while Bridge is running. Bridge therefore is not a one-time configuration utility. It is a session dependency between the mail client and Proton Mail, and start-on-startup is enabled by default for that reason.
What runs inside Proton Mail Bridge
Based on the repository layout, Bridge is a Go application whose module is `github.com/ProtonMail/proton-bridge/v3`. Its `cmd/`, `internal/`, and `pkg/` trees contain application code, while `go.mod` records direct dependencies for IMAP, SMTP, authentication, cryptography, messaging, GUI integration, storage, and other runtime concerns. This is a substantial desktop application rather than a small configuration script.
At the process boundary, the email client connects to local IMAP or SMTP endpoints created by Bridge. Behind that boundary, Bridge has authenticated the Proton Mail account and handles requests through its application and API dependencies. The repository lists the Proton Mail Go API and Proton's `gluon` package, but the README does not provide a detailed internal request sequence. It would therefore be speculative to claim that every message follows a specific path through a particular package.
The on-disk layout is more concrete. The README identifies configuration, cache, data, and temporary directories for Windows, macOS, Linux, and XDG-based systems. It also names `vault.enc`, gRPC configuration files, logs, a gluon database, gluon message storage, update files, a Sentry cache, lock files, and a local file socket. These paths show that Bridge keeps persistent account, application, mail, and update state rather than acting only as a forwarding proxy. The encrypted vault name also makes clear where stored credentials are expected, although the README does not document its internal format or recovery process.
Installing Bridge and creating the first mail-client connection
The README points users to the public Proton Mail Bridge page for the official application and to `BUILDS.md` for detailed build information. It does not give a repository-wide package-manager installation command, so there is no documented `apt`, `brew`, or similar command to reproduce here. This source tree should not be treated as a ready-to-run single binary without following its platform-specific build documentation.
Before starting, check the keychain requirement. macOS and Windows use native credential managers. Linux requires access to the `secret-service` freedesktop.org API. The README identifies Gnome Keyring as usable and also mentions `pass`, while warning that other secret services, including KeepassXC, were not yet supported without major problems. A Linux user should resolve this dependency first.
For a first use with an official distribution, install Bridge and launch it. Sign in with the Proton Mail credentials in the Bridge interface. After login, leave Bridge running and configure the desktop email client from the values shown in the Bridge GUI. The README does not state fixed ports, username syntax, or authentication flags, so those details should be copied from the interface rather than inferred.
The expected result is that the client can synchronize the Proton Mail account over local IMAP or SMTP. Closing the main window is not equivalent to stopping Bridge: the documentation says it continues in the background. If synchronization stops, first verify that Bridge is still running, then compare the mail-client configuration with the values currently displayed.
Credential storage, launcher signatures, and system integration
Proton Mail Bridge has two distinct security-related integrations: credential storage and distribution-file verification. They should not be conflated. Credential storage is handled through native credential managers on macOS and Windows, or through a supported secret service on Linux. The application therefore depends on the host environment rather than treating every supported platform as a self-contained credential database.
The official distribution also separates a launcher from the application. The launcher resides in a protected area accessible to administrators, while application files remain in regular userspace. According to the README, the launcher verifies the application's signature with a hardcoded public key. Application files are signed with Proton's private key. This arrangement is intended to detect tampering and permits automatic updates without requesting a user password.
That mechanism applies to the official packaged distribution. The README does not establish that a manually assembled development build receives the same launcher path. Developers also have several documented environment variables, including `APP_VERSION`, `PROTONMAIL_ENV`, and `VERBOSITY`. Integration testing adds `TEST_ENV`, `TEST_ACCOUNTS`, `TAGS`, and `FEATURES`. These names are useful when interpreting build or test instructions, but the README does not document their complete expected values beyond the stated cases.
Platform directories and the Linux keychain constraint
Bridge uses different directory conventions across operating systems. On Windows, configuration and data default to `%APPDATA%\protonmail\bridge-v3`, cache defaults to `%LOCALAPPDATA%\protonmail\bridge-v3`, and temporary files default to `%LOCALAPPDATA%\Temp`. On macOS, configuration and data use `~/Library/Application Support/protonmail/bridge-v3`, cache uses `~/Library/Caches/protonmail/bridge-v3`, and the temporary location is `$TMPDIR` when set, otherwise `/tmp`.
Linux defaults similarly to `~/.config/protonmail/bridge-v3`, `~/.cache/protonmail/bridge-v3`, and `~/.local/share/protonmail/bridge-v3`, with XDG environment variables providing alternate roots. Bridge also uses a temporary file socket named with the pattern shown in the README as `bridge{4_DIGITS}`. The exact generated digits are not documented and should not be hard-coded by another tool.
The clearest wrong-tool case is a headless or minimally configured Linux host that has no usable `secret-service` implementation. Bridge cannot meet its credential-storage requirement there. A user with KeePassXC alone should not assume support: the README specifically says that work to allow other secret services was still in progress and that Gnome Keyring was the usable option without major problems. A Windows or macOS user avoids that particular Linux constraint because Bridge uses native credential managers.
Local protocol bridging compared with direct Proton Mail clients
The practical alternative is a mail client with direct Proton Mail support. Such a client connects to Proton Mail without Bridge supplying local IMAP and SMTP endpoints. The difference is architectural: direct support keeps account integration in the client, while Bridge introduces a separate process that must run for synchronization and a local configuration boundary that the client must match.
Bridge is useful when the selected desktop client depends on standard IMAP or SMTP and does not provide direct Proton Mail integration. It is less suitable when a direct Proton-capable client already meets the user's needs, because Bridge adds process management, keychain dependencies, local credentials, and another failure point. The README does not provide a compatibility matrix for specific desktop clients, so users should verify support before reorganizing their mail workflow.
The repository also shows that maintenance is active in a narrow, factual sense. The last push was on 2026-09-29, and releases v3.27.1, v3.27.0, and v3.26.0 were published on 2026-09-29, 2026-09-09, and 2026-08-17 respectively. That activity does not remove upgrade costs. Users may need to obtain a new official package, restart the application, and recheck mail-client connection details after upgrading. The repository is licensed under GPL-3.0, with additional licensing details in `COPYING_NOTES.md`; the repository information does not provide legal interpretation of those obligations.
Editorial conclusion
Proton Mail Bridge is appropriate for Proton Mail subscribers who need standard IMAP and SMTP access in a desktop client and can keep Bridge running on the same machine. It is a poor fit for headless systems, unattended external access, or Linux users without a supported secret service. Before adoption, verify client compatibility with the locally displayed settings, the available keychain implementation, and whether the application must remain running continuously.
Frequently asked questions
Can Proton Mail Bridge work without a keychain?
No. The README says a keychain is required. macOS and Windows use native credential managers, while Linux requires the `secret-service` freedesktop.org API.
Why does my email client stop syncing after I close Proton Mail Bridge?
Closing the main window leaves Bridge running in the background, but synchronization requires Bridge to remain active. Check that the application is still running and that the client matches the settings shown in its GUI.
Does Proton Mail Bridge support KeePassXC on Linux?
The README says other secret services, including KeepassXC, were not yet usable without major problems. It identifies Gnome Keyring as the currently usable option without major problems.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/protonmail-proton-bridge)Was this useful?