📬 MailSweep

MailSweep is a high-performance synchronous Rust toolkit to inspect, audit, backup, and clean IMAP mailboxes across 13 European languages. It supports Stalwart, Dovecot, Postfix, Gmail, Fastmail, and Exchange servers.

---

🌟 Key Highlights

• ⚡ Fast Synchronous Engine: Single self-contained native executable with instant startup and sub-second multi-language scans.
• 🛡️ Safety-First Backups: Extracts RFC 822 .eml messages into timestamped ZIP archives with SHA-256 checksums before modifying mailboxes.
• 🗑️ Non-Destructive Cleanup: Relocates clutter to Trash with a 30-day server recovery window instead of permanent deletion.
• 🌍 13-Language European Classifier: Provides heuristic safety tiers for Nordic, Baltic, Western, and Southern European languages.
• 🔒 Inviolable Safety Tier Hierarchy: Protects personal domains, human conversations, invoices, receipts, attachments, and critical legal or medical messages.
• 🏷️ Gmail Protocol Integration: Decodes Google X-GM-EXT-1 extensions, enriches smart labels, and deduplicates messages across virtual folders.

---

🛡️ Safety Tier Precedence Hierarchy

MailSweep evaluates email headers against strict safety tiers before identifying clutter. Safety tiers always take absolute precedence over marketing flags or Gmail smart labels:

1. Tier 0 (Domain Immunity): Grants immunity to custom domains and workplace organizations configured in USER_DOMAINS and USER_ORGANIZATION_KEYWORDS.
2. Tier 1 (Human Conversations): Protects direct human replies and conversation threads with verified In-Reply-To or References headers.
3. Tier 2 (Transactional Documents): Protects messages containing PDF attachments detected through BODYSTRUCTURE inspection or content headers.
4. Tier 3 (Invoices, Receipts & Housing): Protects invoices, payment confirmations, subscriptions, and property management communications across 13 languages.
5. Tier 4 (Critical Records): Protects employment contracts, tax records, health certificates, and legal documents across 13 languages.
6. Tier 5 (Shipping & Calendar): Protects parcel delivery notices, tracking codes, and calendar meeting invitations.
7. Clutter Tiers: Targets feedback surveys, newsletters, marketing campaigns (including Gmail ^smartlabel_promo), social pings, and automated notifications.

---

🚀 Quick Start Guide

1. Download and Install

Option A: Download Pre-Compiled Binary (Recommended)

Download the standalone native executable for your platform from MailSweep Releases:

• Linux x86_64: mailsweep-*-x86_64-unknown-linux-gnu.tar.gz
• Linux ARM64: mailsweep-*-aarch64-unknown-linux-gnu.tar.gz
• Windows x86_64: mailsweep-*-x86_64-pc-windows-gnu.zip

Extract the archive and place mailsweep (and forgejo) in your system PATH or working directory.

Option B: Build from Source

Build the native executable with Cargo:

# Build optimized release binary
cargo build --release

# Optional: Install binary to Cargo bin path
cargo install --path .

---

2. Configuration (.env)

Create a .env file in the project root (see .env.example):

IMAP_SERVER=mail.example.com
IMAP_PORT=993
IMAP_USER=user@example.com
IMAP_PASSWORD=your_secure_password
IMAP_FOLDER=INBOX, INBOX/*, Archive, Archive/*
MAX_EMAILS=0

# Optional: Extra domains or organizations to grant permanent Tier 0 Immunity
USER_DOMAINS=company.com,family.org
USER_ORGANIZATION_KEYWORDS=housingcompany,myorganization

---

3. Run Automated Sweep

# Preview actions in safe Dry-Run mode (default)
mailsweep sweep

# Execute live sweep (Verified Backup -> Non-destructive move to Trash)
mailsweep sweep --execute

---

🛠️ CLI Cheatsheet

MailSweep provides a unified command line interface for all operations:

Command	Description
mailsweep sweep	Execute complete automated pipeline: scan, plan, audit, backup, and clean.
mailsweep scan	Scan mailbox headers and record immutable IMAP UIDs.
mailsweep plan	Generate multilingual classification cleanup plan from scan summary.
mailsweep backup	Download targeted .eml messages and generate compressed backup archive.
mailsweep clean	Relocate or trash targeted clutter messages according to cleanup plan.
mailsweep restore	Restore messages from backup archive to IMAP mailbox.
mailsweep verify	Verify backup archives against live mailbox state.
mailsweep unsubscribe	Generate local web dashboard for brand unsubscription links.
mailsweep audit	Audit classification decisions and backup archives for safety.
mailsweep rules	Validate classification rules or synchronize from upstream sources.
mailsweep test	Run the automated test suite.

Tip for Developers: When developing locally from source, you can also run commands directly with cargo run -- <subcommand> (e.g. cargo run -- sweep).

Read the CLI Reference Manual for complete argument options and examples.

---

🦀 Rust Crate API

MailSweep provides modular, strongly typed domain components in a library crate:

use mailsweep::config::Config;
use mailsweep::pipeline::{MailboxPipeline, SweepOptions};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = Config::load()?;
    let mut pipeline = MailboxPipeline::connect(&config, None)?;

    let mut options = SweepOptions::default();
    options.folders = Some(vec!["INBOX".to_string()]);
    options.dry_run = false;

    let report = pipeline.sweep(options, None)?;
    println!("{}", report.render_text());
    assert!(report.is_clean(), "Safety audit failed!");
    Ok(())
}

Read the Rust API Guide for lifecycle recipes and domain model references.

---

📚 Documentation & Wiki

Find manuals, specifications, and architecture decision records in the MailSweep Wiki:

• 📖 CLI Reference Manual: Command line options, subcommands, and usage examples.
• 🦀 Rust API Reference: Domain models, pipeline lifecycle APIs, and custom transports.
• 📐 Rules Schema Specification: JSON schema specification for 13-language categorization rules.
• ⚡ Internals, Performance & RFCs: IMAP body streaming, ZIP container generation, and RFC standards compliance.
• ❓ Frequently Asked Questions (FAQ): Recovery workflows, edge cases, and server configurations.
• 🏛️ Domain Context: Domain glossary and bounded context definitions.
• 📂 Architecture Decision Records (ADRs): Technical design history and rationale.

---

📁 Project Architecture

mailsweep/
├── src/                        # Synchronous Rust implementation
│   ├── main.rs                 # CLI binary entrypoint (`mailsweep`)
│   ├── lib.rs                  # Library root & domain re-exports
│   ├── cli.rs                  # Clap derive CLI subcommands & progress bars
│   ├── forgejo.rs              # Forgejo issue tracker REST client & CLI
│   ├── pipeline.rs             # Mailbox Pipeline coordinator (sweep, scan, plan, clean, backup)
│   ├── gateway.rs              # Mailbox Gateway (IMAP protocol driver, TLS, UIDVALIDITY)
│   ├── classifier.rs           # Classification Engine (13-language safety tiers)
│   ├── audit.rs                # Safety Auditor (false-positive / false-negative checks)
│   ├── archive.rs              # Backup Archive & Restore (ZIP, manifest, SHA-256)
│   ├── unsubscribe.rs          # Unsubscribe Hub (Brand subscriptions & HTML dashboard)
│   ├── rules.rs                # Rules Registry & multi-lingual fixture validator
│   ├── codecs.rs               # RFC Codecs (RFC 2047 MIME, RFC 3501 UTF-7)
│   ├── models.rs               # Pure domain models (EmailHeader, ScanResult, Folder)
│   ├── config.rs               # Strongly typed configuration (.env loader)
│   ├── error.rs                # Domain error types with safety aborts
│   ├── cache.rs                # Incremental metadata cache
│   └── bin/
│       └── forgejo.rs          # Standalone Forgejo helper binary entrypoint (`forgejo`)
├── tests/                      # Rust integration & golden parity test suite (66 tests)
├── rules.json                  # 13-language European categorization rules & keywords
├── sources.json                # Upstream rule feeds manifest
├── CONTEXT.md                  # MailSweep domain glossary & bounded context
└── docs/                       # Synced documentation & Wiki pages

---

📜 License

MIT