UniversalMailCleaner

🇬🇧 English · 🇩🇪 Deutsche Dokumentation

Local-first Windows desktop app for cleaning IMAP and Gmail mailboxes — rule-based cleanup, large-mail scans, scheduler, and safe trash mode with undo.

1. Architecture & Design Principles
2. Workflow Lifecycle & State Machine
3. Visual Interface & Screenshot Showcase
4. Core Capabilities & Invariants
5. Feature Highlights & Safety Nets
6. Target Personas & Search Intent
7. Comparative Matrix vs. Alternatives
8. Runtime Invariants & Security Guarantees
9. Supported Providers & Protocols
10. Quick Start & Setup
11. Configuration & Credential Safety
12. Scheduler & Automated Maintenance
13. Testing, Verification & Quality Gates
14. Ecosystem & Sibling Tools
15. Third-Party Licenses & Level 1 SBOM
16. Marketing Strategy & Audience Journey
17. License & Attribution
18. Statutory Notice (§ 521 BGB) & Security SLA

UniversalMailCleaner employs a layered desktop architecture designed for non-blocking UI responsiveness, zero credential leakage, and strict local execution boundaries.

flowchart TD
    subgraph UI["Presentation Layer (PySide6)"]
        MW["MainWindow & Primary Tabs"]
        AC["Account Manager Dialog"]
        RL["Rules Engine & Filter Editor"]
        LS["Large Mail & Drive Scanner"]
        SC["Scheduler Widget (QTimer)"]
        ST["Safe Trash & Undo Manager"]
    end

    subgraph Core["Processing & Security Layer"]
        KR["OS Keyring (Windows DPAPI)"]
        WK["Background Worker Thread"]
        PE["Profile Exchange (Secrets-Free)"]
    end

    subgraph Service["Provider Services"]
        IMAP["ImapService (SSL IMAP4 / UIDPLUS)"]
        GMAIL["GmailService (OAuth2 & Drive API)"]
    end

    subgraph Remote["Remote Endpoints"]
        SRV[("IMAP Mail Servers (GMX, Outlook, Gmail)")]
        GOOG[("Google Mail & Drive APIs")]
    end

    MW --> AC
    MW --> RL
    MW --> LS
    MW --> SC
    MW --> ST

    AC --> KR
    RL --> WK
    LS --> WK
    SC --> WK
    ST --> WK

    WK --> IMAP
    WK --> GMAIL

    IMAP --> SRV
    GMAIL --> GOOG

The following sequence details how UniversalMailCleaner isolates credentials, queries mail servers via background worker threads, routes safe-mode deletions to provider trash folders with instant undo guarantees, and requires explicit confirmation for permanent deletions:

sequenceDiagram
    autonumber
    actor User as User / Operator
    participant UI as PySide6 MainWindow
    participant Worker as Background Worker
    participant Keyring as OS Keyring (DPAPI)
    participant Service as ImapService / GmailService
    participant MailServer as Mail Server / API

    User->>UI: Select Account & Run Scan
    UI->>Keyring: Retrieve Encrypted Password / Token
    Keyring-->>UI: Credentials (In-Memory Only)
    UI->>Worker: Dispatch Filter Criteria & Mode
    Worker->>Service: Connect with SSL / OAuth2
    Service->>MailServer: Fetch Message Headers / Size
    MailServer-->>Service: Message Metadata List
    Service-->>Worker: Filtered Candidates
    Worker-->>UI: Populate Results Table

    User->>UI: Select Items & Click Clean Selected
    alt Safe Mode Active (INV-SAFE-03)
        UI->>Worker: Move Messages to Trash Folder
        Worker->>Service: COPY to Trash & STORE +Flags (\Deleted)
        Service->>MailServer: Execute Safe Move
        MailServer-->>Service: Confirmation
        Worker-->>UI: Push UIDs to Transaction Undo Buffer (INV-UNDO-04)
        UI-->>User: Notification: Moved to Trash - Undo Available
    else Permanent Expunge Requested (INV-CONFIRM-05)
        UI->>User: Display Permanent Deletion Warning Dialog
        User->>UI: Confirm Hard Deletion
        UI->>Worker: Issue Hard Expunge
        Worker->>Service: STORE +Flags (\Deleted) & EXPUNGE
        Service->>MailServer: Permanently Purge Messages
        MailServer-->>Service: Purge Confirmed
        Worker-->>UI: Refresh Mailbox State
        UI-->>User: Notification: Permanently Purged
    end

    opt User Requests Undo
        User->>UI: Click Undo Last Deletion
        UI->>Worker: Pop Last Transaction from Undo Buffer
        Worker->>Service: Move UIDs back from Trash to Source Folder
        Service->>MailServer: Restore Messages
        MailServer-->>Service: Restore Confirmed
        Worker-->>UI: Update Table State
        UI-->>User: Notification: Deletion Reverted Successfully
    end

UniversalMailCleaner provides an intuitive PySide6 desktop interface organizing accounts, rule builders, large-item scanners, scheduler presets, and undo capabilities:

UniversalMailCleaner is built around 10 verifiable security, architectural, and operational invariants:

• Multi-Account Management: Simultaneous configuration of SSL IMAP accounts (GMX, Outlook, Web.de, custom mail servers) and Gmail API OAuth2 profiles.
• Lazy Google API Integration: Google client packages are loaded dynamically only when authenticating a Gmail API account. Pure IMAP setups run without Google library dependencies.
• Hardware-Backed Credential Security: Passwords stored in Windows Credential Manager via keyring (Windows DPAPI), falling back to session-only RAM storage if the keyring service is unavailable.
• Rule-Based Filtering Engine: Create composite rules based on age (e.g. older than 90 days), sender pattern, subject keyword, and minimum file/message size.
• Safe Mode by Default: All deletion actions move messages to the provider's trash folder rather than expunging them immediately (INV-SAFE-03).
• Transactional Undo: Instantly restore the previous batch of safe-mode deleted messages with message UID verification (INV-UNDO-04).
• Large-Item Scanner: Tabular overview of heaviest emails and optional Google Drive files, sorted by size with direct selection for cleaning.
• Gmail Storage & Label Analytics: Real-time quota metrics, label-specific cleanup tabs, and selective trash purging.
• Secrets-Free Profile Portability: Export and import cleanup rules and account templates across machines without exposing credentials (INV-PORTABLE-09).
• Configurable Logging: Adjust verbosity via the UMAIL_CLEANER_LOG_LEVEL environment variable.

UniversalMailCleaner is engineered to solve acute pain points for four defined user personas:

• Search Queries: "local email cleaner privacy first", "gdpr compliant imap cleaner", "clean mailbox without cloud service"
• Pain Point: Cannot risk transmitting client data, medical correspondence, or internal memos through cloud SaaS cleanup vendors that monetize email metadata.
• Solution: 100% Local-First desktop execution (INV-LOCAL-01), Zero-Egress design, and hardware-encrypted credential vaults (INV-CRED-02).

• Search Queries: "free up gmail storage without paying", "find large emails fast windows", "clean google drive storage quota"
• Pain Point: Facing imminent 15 GB shared Google quota limits or corporate IMAP mailbox caps, prompting forced monthly cloud subscriptions.
• Solution: High-speed tabular large-item scanner filtering heavy attachments (>10MB, >25MB) across mail and Google Drive for precise reclamation.

• Search Queries: "automate imap inbox cleanup", "desktop email rules scheduler", "safe trash mail cleaner with undo"
• Pain Point: Overwhelmed by tens of thousands of marketing newsletters, automated alerts, and stale notifications across multiple accounts.
• Solution: Automated recurring background scheduler (QTimer), multi-criteria rule chaining, and instantaneous transactional rollback (INV-UNDO-04).

• Search Queries: "open source python imap cleaner", "pyside6 mail management tool", "self hosted email retention cleaner"
• Pain Point: Frustrated by bloated proprietary tools with recurring subscriptions, broken IMAP protocol implementations, and hidden telemetry.
• Solution: Permissive MIT-licensed Python codebase, modular testsuite with 103+ unit tests, and secrets-free portable rule profiles (INV-PORTABLE-09).

UniversalMailCleaner guarantees uncompromised runtime hygiene:

• No Telemetry, No Analytics: Zero tracking beacons, crash report uploaders, or usage analytics are compiled into the binary or scripts.
• Fail-Closed Lock Defense: The application respects local locks and performs non-destructive read operations whenever file conflicts are detected.
• Memory-Isolated Credentials: Passwords decrypted from the Windows DPAPI Credential Vault remain strictly ephemeral in RAM and are scrubbed upon disconnect.

• GMX: imap.gmx.net:993 with SSL
• Outlook / Office 365: outlook.office365.com:993 with SSL
• Gmail via IMAP: imap.gmail.com:993 with App Password
• Gmail via Gmail API: OAuth2 authentication (credentials.json required)
• Web.de: imap.web.de:993 with SSL
• Generic IMAP: Any RFC 3501 compliant IMAP4 server supporting SSL/TLS on port 993

Double-click START.bat in the repository root to launch the desktop application.

# Clone repository
git clone https://github.com/doc-bricks/UniversalMailCleaner.git
cd UniversalMailCleaner

# Install in editable mode
pip install -e .

# Launch application
universalmailcleaner

pip install -r requirements.txt
python mail_imap_cleaner_v1.py

• Configuration File: Stored at %USERPROFILE%\.mail_cleaner\config.json.
• Zero Plaintext Passwords: Credentials and OAuth tokens are strictly decoupled from the JSON configuration and stored securely in Windows Credential Manager (INV-CRED-02).
• Safe Mode Enforced: Safe mode is activated by default on every startup (INV-SAFE-03).

UniversalMailCleaner includes an integrated scheduler_widget.py component driven by Qt's high-precision QTimer:

• Run rule sets automatically at configurable intervals (e.g. every 6 hours, daily, weekly).
• Scheduled operations run strictly in safe mode to prevent unattended data loss.
• Status logs and last-run timestamps are displayed directly in the scheduler status panel.

The test suite validates UI components, background workers, credential vaults, and metadata integrity:

# Run complete test suite (103+ unit tests)
pytest tests -v

# Run metadata and contract tests
pytest tests/test_metadata.py -v

# Code quality and style audit
ruff check .

UniversalMailCleaner is a core utility in the doc-bricks document and mailbox productivity suite under the open-bricks ecosystem:

All third-party dependencies are cataloged in THIRD_PARTY_LICENSES.md:

• PySide6: Qt for Python GUI toolkit (LGPL-3.0-only). Dynamically linked without copyleft contagion.
• keyring: Windows DPAPI credential storage (MIT).
• google-auth-oauthlib & google-api-python-client: Permissive (Apache-2.0). Loaded lazily on demand.
• Level 1 SBOM: Direct and transitive dependencies, SPDX license IDs, upstream repositories, and verification boundaries are audited under Section 7 of THIRD_PARTY_LICENSES.md.

UniversalMailCleaner follows the transparent discoverability framework defined in MARKETING-LOG.txt:

1. Awareness: Search intent targeting privacy-conscious users seeking GDPR-compliant email cleaners without cloud data harvesting.
2. Evaluation: Detailed 10-dimension comparative matrix contrasting local execution with commercial cloud aggregators.
3. Activation: Effortless zero-install start via START.bat or single-command pip installation.
4. Retention: Background scheduler automation and secrets-free portable rule profiles for team and multi-device deployment.

UniversalMailCleaner is open-source software licensed under the MIT License.

Copyright (c) 2026 Lukas Geiger. All rights reserved.
Maintained by doc-bricks under the umbrella of open-bricks.
Canonical attribution and notices are declared in the root NOTICE file.

Diese Software wird unentgeltlich und im Sinne des deutschen Gefälligkeitsrechts (§ 521 BGB) bereitgestellt. Die Haftung des Autors ist auf Vorsatz und grobe Fahrlässigkeit beschränkt. Die Nutzung erfolgt auf eigenes Risiko, insbesondere hinsichtlich der endgültigen Löschung von E-Mails im Permanent-Delete-Modus.

We commit to acknowledging all vulnerability and security reports within 48 hours and providing an initial triage classification within 5 business days per SECURITY.md.