MailSweep Domain Context

MailSweep is a zero-dependency toolkit for scanning, classifying, backing up, and cleaning IMAP mailboxes across 13 European languages.

Language

Mailbox & Protocols

Mailbox Gateway: The deep module managing IMAP connection lifecycles, protocol negotiation (MOVE, UIDPLUS, X-GM-EXT-1), folder encoding, and atomic message operations. Avoid: IMAP Client, Mail Service, IMAP Manager

RFC Codecs & Envelopes: The pure domain module providing multi-pass RFC 2047 MIME decoding, RFC 3501 Modified UTF-7 folder encoding, IMAP BODYSTRUCTURE attachment inspection, Google X-GM-EXT-1 protocol extension parsing, RFC 2369 / RFC 8058 unsubscription header parsing, and environment configuration loading. Avoid: String Helpers, Utilities, Format Utils

EmailHeader: An immutable domain model encapsulating parsed message metadata, RFC headers, attachment flags, Gmail smart labels, and deduplication identity keys. Avoid: Header Dict, Raw Header, Message Item

Message Deduplication: The domain operation identifying identical messages across virtual folders and Gmail categories using canonical deduplication keys. Avoid: Message merging, Duplicate filter

Gmail Label Enrichment: The immutable domain operation combining Gmail category and system labels across multiple mailbox views into an enriched EmailHeader. Avoid: Label mutation, Tag updating

Folder: A mailbox container holding email messages, identified by server name and human-readable decoded Modified UTF-7 representation. Avoid: Directory, Label, Box

UID: An immutable, unique 32-bit integer identifying an email message within a specific folder. Avoid: Sequence number, Message ID

UIDVALIDITY: A server-provided identifier for a folder's UID sequence. Changes indicate mailbox re-indexing and trigger strict safety aborts. Avoid: Cache key, Folder version

Planning & Safety

Mailbox Pipeline: The deep domain coordinator orchestrating end-to-end mailbox scanning, heuristic classification, offline safety auditing, backup archiving, mailbox restore, and cleanup execution behind a single testable interface. Avoid: Mailbox Manager, Sweep Service, Cleanup Orchestrator

Sweep Summary Report: An immutable domain model encapsulating complete end-to-end execution metrics across scan results, cleanup plans, safety audit findings, backup archive manifests, and cleanup outcomes. Avoid: Run Log, Summary Stats, Sweep Output

Scan Result: An immutable domain model encapsulating all scanned email headers, folder UIDVALIDITY snapshots, and mailbox inventory metrics. Avoid: Scan output, Summary data, Scan dump

Scan Cache: An incremental local JSON repository persisting ScanResult metadata indexed by folder name and UIDVALIDITY, enabling sub-second delta scans. Avoid: Database, Local Index, Temp Store

Virtual Folder: A server-aggregated view (such as \All, \Starred, or \Important) that mirrors messages across folders and is excluded from default automated scans, unless discovering Gmail All Mail as a fallback when category folders are absent. Avoid: Real folder, Mailbox, Directory

Classification Engine: The deep domain module evaluating email headers against multi-lingual safety tiers, compiled heuristic patterns, and domain immunity rules to determine retention or cleanup actions. Avoid: Classifier, Rule Runner, Filter Manager

Cleanup Plan: An explicit domain model representing target clutter messages, classified reasons, and folder UIDVALIDITY snapshots. Avoid: Delete targets, Targets list, Action plan

Cleanup Report: A structured domain execution report detailing action outcomes, message counts, and folder metrics from a live or dry-run cleanup. Avoid: Execution summary, Cleanup stats, Run result

Safety Tier: A precedence hierarchy ensuring critical personal, legal, financial, housing, and active human conversation threads are immune from deletion. Avoid: Whitelist, Exception rule

Classification Safety Auditor: The deep domain module auditing scan summaries, cleanup plans, and backup archives against multi-lingual safety heuristics to detect false positives, false negatives, or critical message exposure. Avoid: Audit Script, Checker, Log Inspector

Safety Audit Report: An immutable domain model encapsulating classified safety findings, suspicious clutter detections, false-positive metrics, and sender distributions. Avoid: Audit Log, Audit Output, Check Results

Audit Finding: An immutable domain model encapsulating an individual safety finding with an associated AuditFindingType category (transactional, shipping, protected items, or suspicious trash). Avoid: Audit result, Finding item, Warning object

Clutter: Low-value, marketing, newsletter, or ephemeral automated notifications targeted for archiving or trashing. Avoid: Junk, Spam (unless server-flagged)

Backup & Restore

Backup Archive: A compressed ZIP container packaging raw RFC 822 .eml files, a JSON manifest, and an accompanying SHA-256 checksum file. Avoid: Dump, Snapshot, Tarball

Backup Verification Report: An immutable domain model encapsulating checksum integrity verification and message-level live reconciliation between an offline backup archive and IMAP mailbox state. Avoid: Diff Report, Archive Check, Sync Summary

Backup Item Verification: An immutable domain model representing the live reconciliation state of an individual archived message across source, trash, other folders, or server deletion. Avoid: Verified Item, Checked Email, Diff Entry

Unsubscribe & Brand Management

Unsubscribe Hub: The deep domain module extracting unsubscription endpoints, aggregating sender domains into brand identities, and orchestrating link health verification. Avoid: Unsubscriber, Unsubscribe Manager, Opt-out Service

Brand Subscription: An immutable domain model grouping recurring newsletter or promotional senders under a unified organizational identity with verified opt-out actions. Avoid: Brand, Unsub Item, Sender Group

Rules & Heuristic Governance

Rules Registry: The deep domain module managing multi-lingual rule definition loading, schema & regex validation, 13-language heuristic test execution, and upstream synchronization behind a transport adapter seam. Avoid: Rules Updater, Rules Validator, Rule File Loader

RuleSet: An immutable domain model encapsulating validated keyword pattern tiers, custom domains, property keywords, and RFC provenance metadata. Avoid: Rules Dict, Config JSON, Rule Dump

Rules Validation Report: An immutable domain model encapsulating schema verification results, compiled pattern counts, and multi-lingual heuristic fixture outcomes. Avoid: Validation Log, Test Output, Rule Check Result

Rule Source: An immutable domain model defining an upstream rule feed URL, type (spamassassin, rspamd, ietf_rfcs, mailsweep_json), and target categorization. Avoid: Feed URL, Rule Link

Rule Sources Manifest: An immutable domain model encapsulating multiple external upstream rule sources for federated synchronization. Avoid: Feeds File, URL List, Source Config