[[Uebersicht|← Back to overview]]
# Paperless-ngx – Importing a Proton Mail Account (Configuration Guide)
Technical, English-language configuration guide for connecting a **Proton Mail** account to **Paperless-ngx** and having it ingest mail automatically over IMAP. This document covers **only the configuration path**. It intentionally omits mail rules, operational caveats, and change history.
Derived from the German project notes [[11-E-Mail-Postfaecher]] (general IMAP concept) and [[12-Proton-Bridge]] (verified Proton setup).
## How the connection works
Proton offers no direct IMAP access. A local **Proton Bridge** exposes the mailbox as an IMAP endpoint, and Paperless connects to that endpoint.
```
Proton servers ──(HTTPS, login + 2FA)──► Proton Bridge [dedicated host]
│ local IMAP, STARTTLS, self-signed cert (CN=127.0.0.1)
▼ exposed on LAN at 192.168.2.49:143
socat forwarder (shares the Paperless webserver network namespace)
127.0.0.1:143 → 192.168.2.49:143
▼
Paperless-ngx ── mail account 127.0.0.1:143 (STARTTLS)
```
**Why the loopback detour:** the bridge certificate is issued for **`CN=127.0.0.1` / SAN IP 127.0.0.1** and cannot be reissued for the LAN IP. Paperless verifies the hostname and cannot disable that check. Therefore Paperless must address the bridge as **`127.0.0.1`** (so the certificate name matches), and a small **socat forwarder** — running inside the webserver container's network namespace — relays `127.0.0.1:143` to the bridge's LAN address.
## Prerequisites
- A running **Proton Bridge** that provides IMAP on the LAN (here: `192.168.2.49:143`, STARTTLS). Bridge username = the Proton address; the bridge generates a dedicated **IMAP password**.
- Access to the Paperless stack files (`docker-compose.yml`, `docker-compose.env`) and a shell on the Paperless host (here: container **CT 110**).
## Configuration steps
### 1. Trust the bridge certificate
Export the bridge's self-signed certificate and store it on the Paperless host:
```bash
mkdir -p /opt/paperless/certs
echo | openssl s_client -connect 192.168.2.49:143 -starttls imap 2>/dev/null \
| openssl x509 -outform PEM > /opt/paperless/certs/proton-bridge.pem
```
Mount it into the `webserver` service in `docker-compose.yml`:
```yaml
volumes:
- ./certs/proton-bridge.pem:/usr/src/paperless/certs/proton-bridge.pem:ro
```
Point Paperless at it in `docker-compose.env` (the setting is `…_LOCATION`, **not** `…_FILE`):
```
PAPERLESS_EMAIL_CERTIFICATE_LOCATION=/usr/src/paperless/certs/proton-bridge.pem
```
### 2. Make the bridge reachable as `127.0.0.1:143`
Add a socat forwarder that shares the webserver's network namespace, so `127.0.0.1:143` is the loopback Paperless sees:
```yaml
proton-imap-proxy:
image: docker.io/alpine/socat:1.8.0.3
restart: unless-stopped
network_mode: "service:webserver"
depends_on:
- webserver
command: TCP4-LISTEN:143,fork,reuseaddr,bind=127.0.0.1 TCP4:192.168.2.49:143
```
Apply the changes:
```bash
cd /opt/paperless
docker compose up -d # recreates webserver (mount + env), starts the forwarder
```
### 3. Verify the connection (exactly as Paperless does)
```python
import imaplib, ssl
ctx = ssl.create_default_context()
ctx.load_verify_locations(cafile="/usr/src/paperless/certs/proton-bridge.pem")
M = imaplib.IMAP4("127.0.0.1", 143); M.starttls(ssl_context=ctx)
M.login("<proton-address>", "<bridge-imap-password>") # must return OK
```
Certificate trust, hostname (`127.0.0.1` = certificate SAN), and login must all succeed together.
### 4. Create the mail account in Paperless
Under **Settings → Email → Accounts**, create an account with:
| Setting | Value |
|---|---|
| IMAP server | `127.0.0.1` |
| IMAP port | `143` |
| Security | **STARTTLS** |
| Username | the Proton address |
| Password | the bridge-generated IMAP password (supplied separately, not stored in notes) |
### 5. Set the ingestion scope
Configure the account/processing to use **consumption scope "everything"** (mail **and** attachments):
| Scope | Result |
|---|---|
| Attachments only | attachments only |
| Email only | the message as `.eml` only |
| **Everything (recommended)** | **the message as `.eml` plus each attachment as its own document** |
### 6. Assign the correspondent automatically
Set **assign correspondent from** so the sender becomes the correspondent:
| Option | Result |
|---|---|
| From address | correspondent = `
[email protected]` |
| From name | correspondent = display name, falling back to the address |
## Automatic polling
Once configured, Paperless checks the account **automatically every 10 minutes** (Celery beat task *Check all e-mail accounts* → `paperless_mail.tasks.process_mail_accounts`, schedule `*/10 * * * *`; the default when `PAPERLESS_EMAIL_TASK_CRON` is unset). The Proton Bridge host must be running for a poll to succeed.
To trigger a run immediately instead of waiting:
```bash
docker compose exec --user paperless webserver python manage.py mail_fetch
```
---
**Source:** condensed from [[11-E-Mail-Postfaecher]] and [[12-Proton-Bridge]] · verified on the running system, 2026-07-24.
---
[[Impressum|Impressum]] | [[Datenschutzerklärung|Datenschutz]]