ProtonBridge Headless Mode

Updated 2026-05-10 with latest versions and instructions Proton Mail is a great web email service, but if you've landed here, you've probably run into their lack of support for SMTP. They offer a local bridge application which is designed to run in a desktop environment and enable you to use your Outlook, Thunderbird, etc. email client on that same local computer with your Proton Mail account. However, if you'd like to access your Proton Mail email via another email client on your mobile device or another computer where you can't run their bridge application - that is not supported. This was incredibly frustrating so I figured out how to compile their bridge application without the GUI dependencies in order to run it on any Linux server and expose SMTP / IMAP ports for you to consume from your email client of choice. Challenges There are a few challenges here that we've got to overcome to enable using the proton-bridge project in this way: 1. Application by default requires a GUI Desktop environment to run; On linux it requires Qt and all of it's related dependencies 2. Application listens only on localhost (127.0.0.1) 3. And only on non-standard ports Prerequisites I'll be doing this on an Ubuntu 24.04 server, so we'll need to install some dependencies. 1. sudo apt install libfido2-dev libcbor-dev libssl-dev pkg-config 2. Install golang (the Debian repo one is usually too old - https://go.dev/doc/install) User Account We're going to create a system user account and group for the proton-bridge service to run as. To do this, simply use this useradd command. You'll probably want to add your local user to the proton group as well, in order to make reading it's logs, etc. easier in the future. And finally, create a directory for its logs Keystore Next, lets figure out how to start the thing on a server without a desktop environment. First, you'll want to setup a passphrase-free GPG key. Notice all of these following commands are run in the context of the proton user via sudo -u proton ... This will generate a new key with the name ProtonMail Bridge in your local keyring. Then we'll need to setup a new password database in pass. Now we've got all of the prerequisite steps out of the way! Compiling from source Finally, we can begin installing the actual ProtonMail proton-bridge package. They offer a deb build artifact, but the .deb package that they provide on their download page requires a ton of graphical dependencies that we don't want to install on our server. Fortunately they have a make target called build-nogui setup in their Makefile in the repository. Before we begin compiling it with this special target, there is one change we must make in the source-code. 0.0.0.0 Host By default, the bridge is designed as a local application to run on your desktop machine to enable you to use Thunderbird/Outlook with ProtonMail. With that use-case in mind, it makes sense to only listen on 127.0.0.1 because you'll only be consuming it from the same host. However, we want to run it on a server and connect to it from the outside. So we've got to make a small change in the internal/constants/constants.go file and tell it to listen on 0.0.0.0. This is a shortcut that basically means "all interfaces". Change the line defining Host from Host = '127.0.0.1' to Host = '0.0.0.0'. build-nogui Compilation Next, ensure you're in the root of the proton-bridge repository again and run make build-nogui. This should compile the simple go binary proton-bridge without all of the GUI dependencnies like qt- and the like. After running make build-nogui, we should now have a compiled bridge binary in the root of the repository which does not require a GUI to setup! Run ./bridge --version to ensure it can run and prints the expected output. If that all seems well, symlink this binary to a more appropriate location. Ensure that /usr/local/bin/ is a part of your $PATH. Authentication Finally, we can begin authenticating and getting this thing up and running. Execute the binary with the --cli flag to enter into an interactive CLI mode. In this interactive environment, use the login command to begin the login procedure. This will ask you for your normal web-based ProtonMail username/password and potentially 2FA code. After successfully authenticating, it will begin syncing mails for offline storage. Depending on the age of your account and the size of your mailbox, this may take a while. After that's completed, type info in the interactive shell and it will print out a table of critical information including: - SMTP / IMAP port and host connection details - SMTP / IMAP credentials Daemonizing Finally, we can set this bridge binary to run as a service with a small systemd unit file. And enter something like the following: Remember to potentially adjust a few things here. 1. The ExecStart path to the binary. In my case, I've symlinked the binary from its compilation source folder to /usr/local/bin/proton-bridge. Also notice the --noninteractive flag we're passing here. 2. The user with which this binary will be executed. 3. The paths for the log files. Ensure these directories exist and the user has access to write to them. After saving and closing that file, enable and start the systemd service. This should start the proton-bridge service now and enable it to auto-start on reboot. You can check the current status by executing sudo systemctl status proton-bridge and as the service file indicated, the logs are located at /var/log/proton-bridge/. Ports (Optional) Finally, after starting that service we have the IMAP and SMTP bridge running as a daemon on our server! However, it's still using the odd arbitrary ports. This may be fine if your client application allows you to manually input any number in the port field. However, many Email clients will only allow you to select from a dropdown of a preselected few IMAP/SMTP ports when adding a new Email account. For cases like these, we can use iptables to our advantage! These commands will forward traffic coming from A to destination B. 1. tcp/143 -> tcp/1143 2. tcp/25 -> tcp/1025 Make sure to replace 10.0.1.52 with the IP address of the interface where you'd like proton-bridge to listen on. Summary So with a bit of tweaking we were able to use the pre-existing local bridge GUI application to run a headless server daemon to allow us to connect via SMTP / IMAP from any client to our ProtonMail inboxes!