pi-protonmail

Proton Mail Bridge Pi extension for mailbox discovery, message previews, attachment imports, and profile-based setup.

Use cases

• /protonmail — open the interactive setup hub for profile defaults.
• protonmail_* tools — check Bridge status, list mailboxes, preview messages, and import attachments.

Install

pi install npm:pi-protonmail

For local development:

pi install /absolute/path/to/this/repo

Environment

Set the Proton Bridge connection variables in your Pi environment:

• PROTON_BRIDGE_HOST
• PROTON_BRIDGE_IMAP_PORT
• PROTON_BRIDGE_SMTP_PORT
• PROTON_BRIDGE_IMAP_SECURITY
• PROTON_BRIDGE_USERNAME
• PROTON_BRIDGE_PASSWORD
• PROTON_BRIDGE_DEFAULT_MAILBOX (optional)

These values may be raw strings or 1Password references resolved by the extension.

Profiles and workspace

Profile settings are stored under .pi/protonmail/:

• config.json — workspace-level config
• profiles/<name>/policy.json — per-profile defaults

Profile defaults control the mailbox selection, mailbox filter, period, and optional import workspace override used by LLM-driven mail workflows. Attachment imports default to .pi/protonmail/imports/<profile>/....

Workflow

1. Configure Proton Bridge credentials.
2. Open /protonmail to choose or edit a profile.
3. Use protonmail_* tools for Bridge status, mailbox lookup, message previews, or staged attachment imports.

Publishing

Tagged pushes like v0.1.0 publish to npm through GitHub Actions. The release workflow validates the tag version, runs checks, and publishes with NPM_TOKEN when the version is not already on npm.

Repository notes

• Entry point: src/index.ts
• Main extension logic: src/protonmail.ts
• Native Bridge implementation: src/proton-bridge.ts
• Setup hub: src/hub.ts
• Secret resolution: src/secret-refs.ts

Troubleshooting

• If Bridge status fails, confirm the host, ports, and credentials are correct.
• If list or import commands return nothing, verify the default mailbox and active profile policy.
• If imports fail, check that the target period is set and matches YYYY-MM.