ProtonMail Cleanup Docker

Automatically clean up ProtonMail folders based on retention policies.

Prerequisites

• Docker and Docker Compose installed
• ProtonMail Bridge running on host machine

Setup

1. Copy the example config:

   cp config.json.example config.json

2. Edit config.json with your settings:

   • Update email and password (use Bridge password)
   • Configure folders and retention days
   • Set dry_run: true for testing (or per-folder dry_run overrides)

3. Build and start:

   docker-compose up -d

Usage

View logs:

docker-compose logs -f

Run manually:

docker-compose run --rm protonmail-cleanup python cleanup.py

Stop service:

docker-compose down

Configuration

Edit config.json:

• imap.server: Use host.docker.internal for Bridge on host
• imap.port: Default is 1143 for Bridge
• imap.starttls: Set to true if your Bridge requires STARTTLS (some Linux setups)
• imap.starttls_insecure_skip_verify: Set to true to allow self-signed certs (INSECURE; prefer installing the CA)
• imap.username: Optional; if omitted, email is used for IMAP login
• dry_run: Set to true to test without deleting (per-folder override available)
• log_to_file: Set to false to disable writing to /app/logs/cleanup.log
• log_mailboxes: Set to true to log the list of available mailboxes (helps debug folder names)
• folder_prefix: Optional prefix applied to custom folders (e.g., Folders/ if your custom folders are nested). It is not applied to common system folders (Spam, Trash, Starred, Sent, Drafts).
• imap_timeout_seconds: Optional socket timeout for IMAP operations (default 60s).
• imap_connect_retries: Optional number of connection/login retries (default 5)
• imap_connect_retry_delay_seconds: Optional delay between retries (default 10s)
• sender_rules: Optional global sender-based retention overrides. Each rule:
  • from_contains: substring match against the From header (case-insensitive)
  • subject_contains: substring match against the Subject (case-insensitive)
  • from_regex: regex match against the From header (case-insensitive)
  • subject_regex: regex match against the Subject (case-insensitive)
  • retention_days: positive integer
• folders: Array of folders with retention policies; each entry supports:
  • name: Folder name (exact match)
  • retention_days: Positive integer, or null for unlimited (only sender/subject rules will apply)
  • dry_run (optional): Override global dry_run for this folder
  • sender_rules (optional): Same shape as global sender_rules; evaluated before global rules

Notes:

• The script reads the From header in a case-insensitive manner for sender rules.
• Adjust the retention days and folders to suit your preferences. Using small retention values can result in unintended data loss.

Troubleshooting

• Ensure ProtonMail Bridge is running on host
• Check Bridge allows connections from Docker network
• Verify folder names match your ProtonMail folders exactly

Logging

• Logs are written to the container console and /app/logs/cleanup.log (mapped to ./logs locally).
• Set log_to_file: false in config.json if your runtime filesystem is read-only.
• Validation errors (missing config keys, invalid retention values) are logged and stop the run.

Testing

Install dev deps:

pip install -r requirements-dev.txt

Run tests:

python -m pytest

Local runs (outside Docker)

• Create config.json alongside the script; it will be used automatically if /app/config.json is missing.
• Or set CONFIG_FILE=./config.json (or another path) in your environment/IDE run configuration.