messenger/docs/setup/protonmail.md

Proton Mail Setup

Connect Proton Mail to the messenger platform via Proton Bridge (local IMAP/SMTP).

Prerequisites

• A Proton Mail account (any paid plan — Bridge requires a paid subscription)
• Proton Bridge installed and running locally
• Proton Bridge signed in and configured

1. Install and Configure Proton Bridge

1. Download Proton Bridge from proton.me/mail/bridge
2. Install and launch
3. Sign in with your Proton account
4. Bridge will display local IMAP/SMTP credentials:
   • IMAP: 127.0.0.1:1143
   • SMTP: 127.0.0.1:1025
   • Username: your Proton email
   • Password: Bridge-generated password (NOT your Proton password)

2. Configure Environment Variables

Add to the backend .env file:

# Proton Mail IMAP (incoming, via Bridge)
PROTON_IMAP_HOST=127.0.0.1
PROTON_IMAP_PORT=1143
PROTON_IMAP_USER=yourname@proton.me
PROTON_IMAP_PASS=bridge-generated-password
PROTON_IMAP_TLS=false

# Proton Mail SMTP (outgoing, via Bridge)
PROTON_SMTP_HOST=127.0.0.1
PROTON_SMTP_PORT=1025

# Your Proton email (used to determine message direction)
PROTON_FROM_EMAIL=yourname@proton.me

# Sync interval in milliseconds (default: 60000 = 1 minute)
PROTON_SYNC_INTERVAL=60000

Note: PROTON_IMAP_TLS=false because Bridge handles encryption locally. The connection between the backend and Bridge is plaintext on localhost.

3. Bridge Connection Details

Protocol	Host	Port	Security
IMAP	127.0.0.1	1143	None (localhost)
SMTP	127.0.0.1	1025	None (localhost)

Bridge handles all encryption to Proton servers. Local connections are unencrypted.

4. What Gets Synced

On startup, the ProtonMailSyncService:

1. Connects to Bridge IMAP on localhost
2. Syncs folder list (Inbox, Sent, Archive, Folders, Labels) to email_folders table
3. Fetches messages from each folder (last 30 days on first sync)
4. Parses email headers for threading
5. Creates contacts from sender/recipient addresses
6. Stores messages with provider = 'protonmail' in the unified messages table
7. Polls for new messages on the configured interval

5. Verify Sync

SELECT name, message_count, unread_count FROM email_folders WHERE provider = 'protonmail';
SELECT COUNT(*) FROM messages WHERE provider = 'protonmail';

Troubleshooting

• Connection refused on 127.0.0.1:1143 — Proton Bridge isn't running. Launch it first.
• Authentication failed — Use the Bridge-generated password, not your Proton account password.
• Bridge requires paid plan — Free Proton accounts can't use Bridge. Upgrade to Mail Plus or higher.
• Backend and Bridge on different hosts — Bridge must run on the same machine as the backend (localhost only).