MailSweep Rust Crate API Reference

MailSweep provides high-performance, strongly typed domain modules in a pure Rust crate library (mailsweep).

---

1. Quick Start (Crate Import)

Add mailsweep to your Cargo.toml or use it directly from the workspace:

[dependencies]
mailsweep = { path = "." }

---

2. End-to-End Mailbox Sweep

Use MailboxPipeline to run an automated sweep (scan, plan, audit, backup, and cleanup):

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

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load IMAP configuration from .env or environment variables
    let config = Config::load()?;

    // Connect to the IMAP server over TLS
    let mut pipeline = MailboxPipeline::connect(&config, None)?;

    // Configure sweep options
    let options = SweepOptions {
        folders: Some(vec!["INBOX".into()]),
        action: "trash".into(),
        dest_folder: "Archive".into(),
        trash_folder: None,
        backup_dir: PathBuf::from("backups"),
        backup: true,
        create_zip: true,
        dry_run: true, // Run in safe simulation mode
        audit_safety: true,
        save_snapshots: true,
        cache_path: None,
        cache_dir: Some(PathBuf::from(".mailsweep_cache")),
        user_identifier: Some(config.imap_user.clone()),
        fresh: false,
    };

    // Execute sweep with optional progress callback
    let report = pipeline.sweep(options, None)?;

    println!("{}", report.render_text());
    assert!(report.is_clean(), "Safety audit detected protected items in cleanup!");

    Ok(())
}

---

3. Modular Pipeline APIs

3.1 Scanning Mailbox Headers

use mailsweep::config::Config;
use mailsweep::pipeline::MailboxPipeline;
use std::path::Path;

let config = Config::load()?;
let mut pipeline = MailboxPipeline::connect(&config, None)?;

let scan_result = pipeline.scan(
    Some(&["INBOX".to_string()]),
    500,                                // Batch fetch size
    Some(Path::new("scan_summary.json")), // Output snapshot
    None,                               // Max emails (None = all)
    Some(Path::new(".mailsweep_cache")), // Local cache directory
    Some(&config.imap_user),
    false,                              // Fresh scan bypass
    None,                               // Progress callback
)?;

println!("Total scanned messages: {}", scan_result.len());

3.2 Generating Cleanup Plans

use mailsweep::models::ScanResult;
use mailsweep::pipeline::MailboxPipeline;
use std::path::Path;

let scan_result = ScanResult::load(Path::new("scan_summary.json"))?;
let pipeline = MailboxPipeline::offline(None);

let plan = pipeline.plan(&scan_result, Some(Path::new("targets_to_delete.json")))?;
println!("Target clutter count: {}", plan.len());

3.3 Safety Audit

use mailsweep::plan::CleanupPlan;
use mailsweep::pipeline::MailboxPipeline;
use std::path::Path;

let plan = CleanupPlan::load(Path::new("targets_to_delete.json"))?;
let pipeline = MailboxPipeline::offline(None);

let audit_report = pipeline.audit_plan(&plan, Some("Weekly Sweep"));
if !audit_report.is_clean() {
    eprintln!("Warning: Safety audit identified protected items in plan!");
}

3.4 Backup & Restore

use mailsweep::archive::BackupArchive;
use std::path::Path;

// Open and verify an offline backup ZIP archive
let archive = BackupArchive::open(Path::new("backups/email_backup_20260824.zip"))?;
let (is_valid, msg) = archive.verify_integrity();
println!("Integrity: {msg} (valid: {is_valid})");

// Query messages inside the backup
let results = archive.iter_messages("Invoice", "", "")?;
println!("Matching invoices in archive: {}", results.len());

---

4. Multilingual Classification Engine

use mailsweep::classifier::ClassificationEngine;
use mailsweep::models::{Action, EmailHeader, SafetyTier};
use mailsweep::rules::RuleSet;

// Load validated 13-language rule set
let rules = RuleSet::load_default();
let engine = ClassificationEngine::new(rules);

let mut header = EmailHeader::default();
header.subject = "Työsopimus ja palkkalaskelma".to_string();
header.sender = "hr@company.fi".to_string();

let decision = engine.classify(&header);
assert_eq!(decision.action, Action::Keep);
assert_eq!(decision.tier, SafetyTier::Tier4CriticalLegal);