Protonmail

Protonmail

Send, read, search, and organize Protonmail messages via Proton Bridge + himalaya.

Script: scripts/proton.py Config: config/config.json

First-time setup

When config/config.json is missing, the skill outputs SETUP_REQUIRED instead of running commands. Follow this two-step flow:

Step 1: Install Proton Bridge

Proton Bridge runs locally and exposes standard IMAP/SMTP on localhost. It must be installed and logged in before the skill works.

1. Download the .deb from https://proton.me/bridge/install
2. Install: sudo apt install ./protonmail-bridge_*.deb
3. Set up pass for credential storage (Bridge requires it — see references/setup.md for details)
4. Log in via Bridge CLI: protonmail-bridge --cli then login
5. Run info inside the Bridge CLI to get the Bridge password (a generated string like abcdefghijklmnop)
6. Start Bridge as a systemd user service so it runs in the background

The Bridge password is NOT your Proton account password. It is a randomly generated credential that Bridge creates for local IMAP/SMTP access. You get it from the info command inside Bridge CLI.

Set the Bridge password in OpenClaw's secrets system:

Use /secret set PROTON_BRIDGE_PASSWORD and paste the Bridge password from step 5.

Step 2: Configure the skill

Ask the user for:

1. Proton email address (e.g., you@proton.me or you@pm.me)
2. Display name (for outgoing emails)

Then run:

python3 $PROTON setup configure --email USER_EMAIL --display-name "USER_NAME"

This writes config/config.json, generates the himalaya config, and verifies connectivity to Bridge.

Quick reference

PROTON=~/.openclaw/workspace/skills/protonmail/scripts/proton.py

# Email
python3 $PROTON email list                                       # Latest 10
python3 $PROTON email list --count 20                            # Latest 20
python3 $PROTON email list --folder Sent                         # Sent folder
python3 $PROTON email list --unread                              # Unread only
python3 $PROTON email read <id>                                  # Read email by ID
python3 $PROTON email read <id> --folder Sent                    # Read from specific folder
python3 $PROTON email send <to> <subject> --body-stdin <<'EOF'    # Send email
body here
EOF
python3 $PROTON email reply <id> --body-stdin <<'EOF'            # Reply to email
body here
EOF
python3 $PROTON email search "from someone"                      # Search emails
python3 $PROTON email search "from someone" --folder Sent        # Search specific folder
python3 $PROTON email move <folder> <id>                         # Move email to folder
python3 $PROTON email move <folder> <id> --from Spam             # Move from specific folder
python3 $PROTON email delete <id>                                # Move to Trash
python3 $PROTON email delete <id> --folder Spam                  # Delete from specific folder

# Folder
python3 $PROTON folder purge <folder>                            # Purge all emails from folder

# Setup
python3 $PROTON setup configure --email X --display-name X       # Write configs
python3 $PROTON setup verify                                     # Smoke test Bridge + himalaya
python3 $PROTON --test                                           # Self-test

Email

Listing emails

python3 $PROTON email list                        # Latest 10
python3 $PROTON email list --count 20             # Latest 20
python3 $PROTON email list --folder Sent          # Sent folder
python3 $PROTON email list --unread               # Unread only

Reading emails

python3 $PROTON email read 142                    # Read by ID from list output
python3 $PROTON email read 142 --folder Sent      # Read from a specific folder

Note: Email IDs are folder-specific. If you listed emails from --folder Sent, use --folder Sent when reading them too.

Sending emails

IMPORTANT: Always use --body-stdin with a single-quoted heredoc (<<'EOF'). This prevents the shell from interpreting $ signs, backticks, and other special characters in the email body. Without this, text like $5,000 silently becomes ,000.

python3 $PROTON email send "recipient@example.com" "Subject line" --body-stdin <<'EOF'
Body of the email.

The $5,000 payment is confirmed.
EOF

Default From address: Uses the account_email field in config/config.json.

IMPORTANT: Always ask permission before sending emails on behalf of the user.

Replying to emails

IMPORTANT: Always use --body-stdin with a single-quoted heredoc, same as sending.

python3 $PROTON email reply 142 --body-stdin <<'EOF'
Thanks, that works for me.

The $500 deposit is fine.
EOF

Searching emails

Uses himalaya query syntax (positional args). Defaults to INBOX, 50 results:

python3 $PROTON email search "from Alice"
python3 $PROTON email search "subject invoice"
python3 $PROTON email search "after 2026-02-01"
python3 $PROTON email search "from Alice and after 2026-01-01"
python3 $PROTON email search "subject receipt" --folder Sent     # Search specific folder
python3 $PROTON email search "from Alice" --count 100            # More results

Moving emails

python3 $PROTON email move "Trash" 142
python3 $PROTON email move "Archive" 142
python3 $PROTON email move "INBOX" 142 --from Spam    # Move from a specific source folder

Protonmail folders: INBOX, Sent, Drafts, Trash, Spam, Archive, All Mail.

Note: Argument order is <folder> <id> (folder first, same as himalaya). Without --from, moves default to INBOX as the source folder.

Deleting emails

python3 $PROTON email delete 142                       # Delete from INBOX (default)
python3 $PROTON email delete 142 --folder Spam         # Delete from specific folder

Folder operations

Purging a folder

Permanently deletes all emails in a folder. The folder itself remains but is emptied.

python3 $PROTON folder purge "Spam"
python3 $PROTON folder purge "Trash"

This is non-interactive (no confirmation prompt), so always confirm with the user before purging.

Troubleshooting

Agent instructions

• Bridge password != Proton password. The Bridge password is a generated string from protonmail-bridge --cli > info. Never ask the user for their Proton account password.
• SETUP_REQUIRED signal: If any command outputs this, stop and walk the user through setup. Do not retry the command.
• Bridge must be running. If connection fails, check systemctl --user status protonmail-bridge first.
• Self-signed certificates. Bridge uses a self-signed TLS cert for localhost. IMAP uses start-tls with the exported cert for verification. SMTP uses encryption.type = "none" because it's localhost-only — Bridge handles the encrypted connection to Proton's servers.
• First sync delay. After initial Bridge login, it takes several minutes to sync all mail. Warn the user if they just set up Bridge and see no emails.
• Always ask before sending. Never send an email without explicit user confirmation.

Notes

• Config: config/config.json — email address, display name, binary paths, himalaya config location.
• Auth: Bridge password entered via /secret set PROTON_BRIDGE_PASSWORD, written to config/auth (chmod 600) by setup, read by himalaya at runtime.
• Ports: Bridge defaults to IMAP 1143, SMTP 1025 on localhost.
• Self-test: python3 $PROTON --test — verifies config and Bridge connectivity.
• Full setup guide: See references/setup.md for Bridge installation and pass setup details.