email_tunnel

Poll Proton Bridge via IMAP and inject messages into a local SMTP server (e.g., Haraka). The script is designed for headless, continuous operation with basic safety/observability baked in.

What it does

Connects to Proton Bridge IMAP via STARTTLS and selects a required folder.
Polls for new messages by UID, fetches each, and relays it verbatim to a local SMTP server using the original headers.
Strips Bcc, deduplicates recipients, and skips malformed addresses.
Tracks progress in a JSON state file so messages are processed once, even across restarts.
Retries IMAP fetch/search and SMTP delivery with bounded attempts/backoff; advances state past permanent delivery failures to avoid loops.
Enforces single-instance execution via a pidfile lock.
Emits scrape-friendly INFO logs each cycle with counts, last UID, and cycle duration.

Requirements

Python 3.x
Proton Bridge IMAP reachable at the configured host/port
Local SMTP server reachable (e.g., Haraka bound to a non-25 port)

Configuration (environment variables)

IMAP_IP (required): Proton Bridge IMAP host.
IMAP_PORT (required): Proton Bridge IMAP port (typically 1143).
IMAP_USER (required): IMAP username.
IMAP_PASSWORD (required): IMAP password.
IMAP_FOLDER (required): IMAP folder to poll; must exist (no fallback).
IMAP_TLS_VERIFY (default 1): Set to 0/false to disable cert/hostname checks (dev only).
SMTP_IP (default 127.0.0.1): SMTP host to deliver to.
SMTP_PORT (default 2525): SMTP port to deliver to.
POLL_INTERVAL (default 15): Seconds between mailbox polls.
STATE_FILE (default ./state.json): Path to persist last processed UID.
PIDFILE (default /tmp/email_tunnel.pid): Pidfile for single-instance lock.
LOG_LEVEL (default INFO): Standard logging levels (DEBUG, INFO, etc.).

Usage

export IMAP_IP=127.0.0.1
export IMAP_PORT=1143
export IMAP_USER=...
export IMAP_PASSWORD=...
export IMAP_FOLDER=loomio
export SMTP_IP=127.0.0.1
export SMTP_PORT=2525
python3 email_tunnel.py

Run under a process supervisor (systemd, supervisord, etc.) so restarts and log rotation are handled.

Operational behavior

State tracking: STATE_FILE records the last successfully handled UID. It is only advanced after successful delivery, or after a logged DeliveryError to avoid reprocessing a permanently failed message.
Retries: IMAP SEARCH/FETCH and SMTP SEND are retried up to 3 times with small backoff. Persistent failures log and move on.
Single instance: pidfile lock prevents multiple concurrent runs; stale pidfiles are replaced if the recorded PID is not running.
Metrics logging: every poll cycle emits a single INFO line with metrics prefix and key/value pairs (cycle_processed, cycle_delivered, cycle_failed, session_*, last_uid, cycle_duration_ms).
Missing state: if STATE_FILE is absent on startup, the script initializes it to the current max UID (or 0 for an empty mailbox) to avoid reprocessing the entire mailbox.

Notes and safety

Leave IMAP_TLS_VERIFY enabled in production; disable only for trusted, local endpoints.
Ensure the STATE_FILE and PIDFILE paths are writable by the service user.
If delivering to a server that rejects certain recipients, the script will log the error, advance the UID, and continue.

Troubleshooting

Increase verbosity with LOG_LEVEL=DEBUG to see raw message dumps and IMAP folder listings.
If the script exits immediately, verify required env vars and that IMAP_FOLDER exists on the server.
For pidfile conflicts, check the process holding the PID or remove a stale pidfile if no process is running.***

3.6 KiB Raw Blame History