MailProcessor

System tray launcher for the three Universal Mail Tools.

Language: English · Deutsch

Note

For AI agents and automated tools, key architecture and interface metadata are indexed in llms.txt.

---

Quick Navigation

• What it does
• Features
• System Architecture & Workflow
• Lifecycle & Execution Sequence
• Installation
• Windows Release
• Platform Scope
• Governance & Runtime Invariants
• Requirements
• Development Checks
• Configuration
• Related Tools
• License

---

What it does

MailProcessor sits in the Windows system tray and gives you one-click access to:

• Universal Mail Cleaner — Clean an IMAP mailbox by rules
• Universal Docs Grabber — Download documents and attachments from mail
• Universal Invoice Mail — Extract invoices automatically from mail

Features

• System tray icon: launch any tool via right-click at any time
• First run: setup wizard with automatic scan for installed tools
• GitHub installer: download tools directly from GitHub Releases
• Version numbers shown in tray menu (read from each tool's CHANGELOG.md)
• Settings: change paths, remove tools, add manually
• Read-only snapshot export as mailprocessor-suite-v1.json for local reference; no web or mobile companion is active
• Windows autostart (registry entry)
• Bilingual: German / English

Data and network scope

MailProcessor stores its launcher configuration on the device. When a user starts a tool download in the setup wizard, the launcher requests release metadata from GitHub and downloads that tool's release archive. No telemetry implementation was found in the reviewed launcher source. The separately launched mail tools have their own data flows; this finding does not describe or limit their network behavior. See the launcher privacy notice draft.

System Architecture & Workflow

flowchart TD
    User(["User (Desktop Interaction)"]) -->|"right-click / click"| Tray["Windows System Tray (MailProcessor)"]

    subgraph Core ["MailProcessor Desktop Core"]
        Tray -->|"reads / writes state"| Config["Config Manager<br/>(%LOCALAPPDATA%/MailProcessor/config.json)"]
        Tray -->|"opens configuration"| SettingsDialog["Settings Dialog (Paths & Autostart)"]
        Tray -->|"exports offline state"| Snapshot["Snapshot Exporter (mailprocessor-suite-v1.json)"]
        Tray -->|"first launch / missing tools"| Wizard["Setup Wizard & Local Scanner"]
        Wizard -->|"downloads releases"| Downloader["GitHub Releases Downloader (Zip-Slip Safe)"]
    end

    subgraph Tools ["Universal Mail Suite (Subprocesses)"]
        Tray -->|"launches tool (subprocess)"| Tool1["Universal Mail Cleaner<br/>(Rule-based IMAP Mailbox Cleaner)"]
        Tray -->|"launches tool (subprocess)"| Tool2["Universal Docs Grabber<br/>(Document & Attachment Grabber)"]
        Tray -->|"launches tool (subprocess)"| Tool3["Universal Invoice Mail<br/>(Automated Invoice Extractor)"]
    end

    Downloader -->|"installs archive to"| LocalTools["%LOCALAPPDATA%/MailProcessor/tools/"]
    LocalTools -.->|"provides binaries"| Tools

Loading

Lifecycle & Execution Sequence

sequenceDiagram
    autonumber
    actor User as "Desktop User"
    participant Tray as "Tray Application (PySide6)"
    participant Cfg as "ConfigManager"
    participant Wiz as "Setup Wizard / Downloader"
    participant GH as "GitHub Releases API"
    participant Proc as "Subprocess Runner"
    participant Tool as "Universal Mail Tool"

    User->>Tray: Launch MailProcessor (main.py / start.bat)
    Tray->>Cfg: Load settings (%LOCALAPPDATA%/MailProcessor/config.json)
    alt First Run / Unconfigured Tools
        Tray->>Wiz: Show Setup Wizard
        Wiz->>Wiz: Scan sibling folders for installed tools
        opt Download missing tools
            Wiz->>GH: Fetch latest release assets (Zip-Slip protected)
            GH-->>Wiz: Release archive ZIP
            Wiz->>Wiz: Extract to %LOCALAPPDATA%/MailProcessor/tools/
        end
        Wiz->>Cfg: Save discovered & configured tool paths
    end
    Tray-->>User: System tray icon active in notification area

    User->>Tray: Right-click tray icon & select tool
    Tray->>Proc: launch_tool(tool_id, tool_path)
    Proc->>Tool: Spawn unprivileged detached process (RunAsInvoker)
    Tool-->>User: Universal Mail Tool GUI opens (Clean / Grab / Invoice)

    opt Snapshot Export
        User->>Tray: Select "Export Snapshot"
        Tray->>Cfg: Read tool versions & metadata
        Tray->>Tray: Sanitize paths & write mailprocessor-suite-v1.json
        Tray-->>User: Confirmation notification
    end

Loading

Installation

1. Install Python 3.10+
2. Install dependencies:

   pip install -r requirements.txt

3. Launch:

   start.bat

   or

   python main.py

4. Select the desired tools in the setup wizard

Windows Release

• Local release artifacts are staged in releases/v0.1.0/
• Rebuild the Windows executable with build_exe.bat
• The packaged binary is named MailProcessor-0.1.0-desktop.exe

Microsoft Store readiness

The Microsoft Store is currently deferred. MailProcessor launches external desktop processes, writes its per-user autostart entry, and downloads selected GitHub release archives, so any package requires both runFullTrust and internetClient plus a separate privacy, packaging, and certification review.

The read-only gate can be run by humans or automation and emits stable JSON:

python store_readiness.py --release-dir <existing-vX.Y.Z-release-folder>
python store_readiness.py --release-dir <existing-vX.Y.Z-release-folder> --json

Exit code 0 means every gate passed; exit code 2 means at least one blocker remains. The audit never builds, signs, uploads, or submits a package.

Platform Scope

MailProcessor is a Windows desktop tray launcher. The former web/PWA companion was intentionally removed after its use-case review; the redacted snapshot is not a synchronization interface or a mobile product. macOS and Linux retain a source-level contract only, not a packaged end-user release; its reproducible check and explicit non-goals are documented in MACOS_LINUX_SOURCE_SMOKE.md. Android/iOS, Capacitor, and server synchronization have no active product surface. A future native or device claim requires a new product decision plus its own build and device/emulator acceptance. Store blockers and the next required evidence are tracked in RELEASES.md.

Governance & Runtime Invariants

The following identifiers summarize observed product behavior and security boundaries:

Invariant ID	Name	Standard / Policy	Observed behavior
INV-DATA-01	Launcher data and network scope	Observed source behavior	Launcher configuration is stored locally. User-started tool downloads contact GitHub Releases; separately launched tools have their own data flows. No telemetry implementation was found in the reviewed launcher source.
INV-NOELEV-02	Non-Elevation & RunAsInvoker	Windows Least Privilege	Runs exclusively as standard unprivileged user. Never requests UAC elevation (runAsInvoker).
INV-ZIPSLIP-03	Zip-Slip Traversal Defense	CWE-22 Security Standard	Tool downloads from GitHub releases validate archive member paths to prevent directory traversal attacks before extraction.
INV-CFGISO-04	Local AppData Isolation	Windows AppData Convention	Configuration is isolated under %LOCALAPPDATA%\MailProcessor\config.json. No registry pollution except optional per-user autostart entry.
INV-PROCLIF-05	Safe Subprocess Lifecycle	Clean Process Separation	Launches Universal Mail Tools via detached unprivileged subprocesses (subprocess.Popen) preventing parent tray lockups or cascaded crashes.
INV-REDACT-06	Snapshot path hints	Data handling	The export replaces local data-root paths; other paths may retain the last one or two folder names. Review the file before sharing.
INV-OSPAR-07	Cross-Platform Source Smoke Contract	Multi-OS Integrity	Primary product surface is Windows Desktop Tray; multi-platform smoke test matrix verifies source-level compatibility across Ubuntu and macOS.
INV-SLA-08	Security Response & Triage SLA	Responsible Disclosure	48-hour response SLA and 5-business-day triage commitment through security@ellmos.ai and GitHub Security Advisories.

Requirements

• Python 3.10+
• PySide6 6.x
• One or more Universal Mail Tools (auto-downloaded via wizard)

Development Checks

python -m pytest -q
python -m compileall .

Current local test suite: 79 Pytest tests.

Configuration

Settings are stored in %LOCALAPPDATA%\MailProcessor\config.json.

Tools are installed to %LOCALAPPDATA%\MailProcessor\tools\.

Related Tools

Part of the doc-bricks mail suite and open-bricks umbrella:

Tool	Category	Role & Description	Status	Repository
UniversalMailCleaner	Mail Hygiene	Rule-based IMAP mailbox cleaner with safe mode	Active / Supported	doc-bricks/UniversalMailCleaner
UniversalDocsGrabber	Mail Extraction	Download documents and attachments from IMAP mail	Active / Supported	doc-bricks/UniversalDocsGrabber
UniversalInvoiceMail	Mail Extraction	Extract invoices and receipts automatically from IMAP mail	Active / Supported	doc-bricks/UniversalInvoiceMail
FormularErstellen	Document Tools	Interactive form generator and document template engine	Sibling Tool	doc-bricks/FormularErstellen
PDFtoPDFocr	Document OCR	Searchable PDF OCR pipeline and document text recognition	Sibling Tool	doc-bricks/PDFtoPDFocr
DokuZen	Knowledge Hub	Desktop document organizer, file classifier, and knowledge hub	Sibling Tool	doc-bricks/DokuZen
open-bricks	Umbrella	Umbrella ecosystem, shared policies, and open-source catalog	Umbrella Hub	open-bricks/open-bricks

License

MIT License — see LICENSE