Marbler Help

Everyday

Proton Mail on Marbler, step by step

Bring Proton Mail into Marbler around the clock with Proton Mail Bridge and Marbler's mail sender, on your own computer or a home server.

Why it takes a few steps

Proton Mail keeps your mail encrypted. Proton lets outside apps in only through its own helper app, Proton Mail Bridge, and only after you sign in to Bridge with your Proton account. Nobody else can do that sign-in for you, Marbler included. So adding Proton Mail can't be one click like Gmail.

Bridge only lets in programs on the machine it runs on, or on a private network you set up. Marbler's mail sender is a small program that runs right next to Bridge. It reads your mail from Bridge and sends it to Marbler, so your mail shows on your phone and the web too.

There are two ways to run it:

  • Way A: on your own computer. Bridge and the mail sender run on a computer you already use. Mail arrives while that computer is on, and catches up when it comes back.
  • Way B: on a home server or NAS. Bridge and the mail sender run as two containers on a machine that is always on. Mail arrives all day and night.

Both ways need the same two things from you: your sign-in to Bridge, and a token from Marbler.

Step 1: get a token from Marbler

  1. In Marbler, open Settings and pick Mail.
  2. Tap Connect a mail sender.
  3. Tap Copy. You will not see this token again, so save it now. You'll put it in a file in the next steps.

This token can only send mail into Marbler. It can't read your tasks or notes, and it can't make other tokens. To stop a mail sender, revoke its token in Settings › Agent tokens. It shows there as Mail sender.

Way A: on your own computer

  1. Download Proton Mail Bridge from Proton's website, install it, open it and sign in with your Proton account.
  2. Wait for Bridge to finish syncing your mail. The first time can take a while.
  3. In Bridge, click your account. It shows a username and a password for mail apps. This password is made by Bridge. It is not your Proton password. Never type your Proton password into Marbler.
  4. Make a folder for the mail sender, for example marbler-mail-sender. In it, make a folder named secrets and put two files in it: - marbler-token, holding the token from step 1, - bridge-password, holding the Bridge password. Make both files readable only by you (on Linux and macOS: chmod 600 secrets/*).
  5. Get the mail sender from the Marbler source code (folder integrations/mail-sender) and start it with Node 22 or newer:

``sh MARBLER_URL=https://marbler.app \ BRIDGE_HOST=127.0.0.1 BRIDGE_PORT=1143 \ BRIDGE_USER=you@proton.me \ MARBLER_TOKEN_FILE=secrets/marbler-token \ BRIDGE_PASSWORD_FILE=secrets/bridge-password \ STATE_DIR=state \ node integrations/mail-sender/sender.cjs ``

Put your Bridge username in BRIDGE_USER. If you run your own Marbler server, put its address in MARBLER_URL.

The mail sender says what it is doing, one line at a time. The first time it says it trusts Bridge's certificate, then it adds the Proton Mail account in Marbler and sends your last 90 days of mail. After that it looks every 2 minutes.

Way B: on a home server or NAS

You need a machine that is always on and can run containers. Bridge and the mail sender run as two containers on a private network of their own. Nothing is opened to the internet, or even to the rest of your home network.

  1. Make a folder, for example proton-mail, and put this in it as compose.yaml. Put your Proton address in BRIDGE_USER.

``yaml services: bridge: # A community-made container of Proton Mail Bridge. image: shenxn/protonmail-bridge:latest restart: always volumes: - ./bridge:/root networks: [mail] sender: build: context: ./marbler dockerfile: integrations/mail-sender/Dockerfile restart: always depends_on: [bridge] environment: MARBLER_URL: https://marbler.app BRIDGE_HOST: bridge BRIDGE_PORT: "143" BRIDGE_USER: you@proton.me MARBLER_TOKEN_FILE: /run/secrets/marbler-token BRIDGE_PASSWORD_FILE: /run/secrets/bridge-password volumes: - ./secrets:/run/secrets:ro - ./sender:/data mem_limit: 128m cpus: 0.25 networks: [mail] networks: mail: ``

  1. Put the Marbler source code in a folder named marbler next to it. The mail sender is built from it. It installs nothing from the internet beyond the Node base image.
  2. Sign in to Bridge once. This is the step only you can do:

``sh docker compose run --rm bridge init ``

At the >>> prompt type login, then your Proton email, your Proton password and your two-factor code. When it says it is done, type info. Copy the Username and Password it shows, then type exit.

  1. Make a folder named secrets with the two files from Way A, step 4 (marbler-token and bridge-password). The mail sender runs as user 1000, so give that user the files and the sender folder: chown -R 1000 secrets sender && chmod 600 secrets/*.
  2. Start both:

``sh docker compose up -d docker compose logs -f sender ``

The log says when the account is added and when mail is sent. The mail sender is small: about 35 MB of memory and almost no processor time between looks.

Good to know

  • Read state and folders. Emails you read, star, move, archive or delete in Marbler are changed in Proton too, through Bridge. Changes made in Proton show in Marbler on the next look.
  • The certificate. Bridge locks its connection with its own certificate. The mail sender trusts the one it sees the first time and nothing else after. If it ever changes, the mail sender stops before sending the password, and the account in Settings › Mail says why. If you know why it changed (you reinstalled Bridge), delete the file state.json in the sender's folder and start it again.
  • Removing. Removing the Proton Mail account in Marbler stops the mail sender for good; it never adds the account back by itself. To add it again, delete state.json and start it again. To stop it entirely, revoke its token in Settings › Agent tokens.
  • Bridge signed out. Proton sometimes signs Bridge out, for example after you change your Proton password. The account in Settings › Mail then says it couldn't read Bridge. Sign in to Bridge again (Way B, step 3).