python/proton-mail-bridge-client
3
Fork 0
Code Issues Pull requests 1 Projects Releases 2 Packages Activity Actions
2 releases 2 tags
  • v1.0.0 b82f47f023

    Release v1.0.0 Stable

    thomass released this 2026-01-17 18:19:56 +01:00 | 9 commits to main since this release

    Initial release of proton-mail-bridge-client.

    Added

    Email Operations

    • list_mails(folder, limit, offset, unread_only, sort_by_date, include_labels) - List emails with filtering and pagination
    • read_mail(email_id, folder) - Read full email content with proper encoding handling
    • send_mail(to, subject, body, cc, bcc, body_html) - Send emails via SMTP
    • delete_mail(email_id, folder, permanent) - Delete emails (move to Trash or permanent)
    • move_mail(email_id, source_folder, destination_folder) - Move emails between folders
    • find_emails(folder, subject, sender, recipient, since, before, unread_only, limit) - Search emails using IMAP SEARCH
    • get_email_by_message_id(message_id, folder) - Find email UID by Message-ID header
    • add_label(email_id, folder, label_name) - Add label to email
    • remove_label(email_id, label_name, folder) - Remove label from email

    Folder Management

    • list_folders() - List all mail folders
    • create_folder(name) - Create folders with automatic nested path creation
    • rename_folder(old_name, new_name) - Rename or move folders
    • delete_folder(name) - Delete custom folders (system folders protected)
    • folder_exists(name) - Check folder existence

    Label Management

    • list_labels() - List all user-created labels
    • create_label(name) - Create labels (flat structure)
    • rename_label(old_name, new_name) - Rename labels
    • delete_label(name) - Delete labels
    • label_exists(name) - Check label existence

    Connection & Configuration

    • Persistent IMAP/SMTP connections with automatic reconnection
    • Exponential backoff retry logic (1s, 2s, 4s delays)
    • Thread-safe connection access using RLock
    • Context manager pattern for automatic cleanup
    • Environment variable configuration support
    • SOPS-encrypted credential support (.env.sops)

    Data Models

    • Folder - Mail folder with metadata
    • EmailMetadata - Lightweight email headers for listing
    • Email - Full email content with plain text and HTML bodies

    Exception Hierarchy

    • ProtonMailBridgeError - Base exception
    • BridgeConnectionError, BridgeAuthenticationError, BridgeTimeoutError
    • SMTPConnectionError, SMTPAuthenticationError, SMTPTimeoutError
    • ConfigurationError, SOPSDecryptionError
    • FolderError, FolderNotFoundError, FolderAlreadyExistsError, InvalidFolderNameError
    • LabelError, LabelNotFoundError, LabelAlreadyExistsError, InvalidLabelNameError
    • EmailError, EmailNotFoundError, InvalidEmailFormatError, EmailSendError, EmailDeleteError, InvalidRecipientError

    Technical Details

    • 497 unit tests passing
    • Python 3.12-3.14 support
    • Zero external runtime dependencies (stdlib only)
    • Full type hints throughout codebase
    • Facade pattern with ProtonMailClient as single public interface

    Known Limitations

    • No attachment handling
    • No mark read/unread
    • No batch operations
    • No async support
    • Requires ProtonMail Bridge running locally
    Downloads