MailSweep Frequently Asked Questions (FAQ)

Answers to common questions regarding mailbox scanning, backups, safety rules, and IMAP configuration.

---

1. Safety & Dry-Run Defaults

Q: Does MailSweep delete or move any emails without confirmation?

No. MailSweep executes in dry-run mode by default across every command:

• mailsweep scan and mailsweep plan use read-only IMAP operations (BODY.PEEK) and do not modify email flags or folders.
• mailsweep clean and mailsweep sweep simulate all actions and show email counts without modifying the server.
• The pipeline moves clutter to Trash only when you specify the --execute flag.

---

2. Backups & Interrupted Runs

Q: What happens if an active backup disconnects or stops?

• No data loss occurs: The archiver writes each email batch to disk immediately as individual .eml files in backups/.
• Automatic Resume: Running mailsweep backup detects previously downloaded .eml files, skips completed messages, and downloads remaining emails.
• Safety Verification: When running mailsweep sweep --execute, live cleanup runs only after the backup finishes with a verified SHA-256 checksum.
• Fresh Start: Pass the --fresh flag to discard partial backups and restart the download:

  mailsweep backup --fresh
  

Q: What timestamp does MailSweep assign to a resumed backup?

The final compressed .zip archive, companion .sha256 checksum, and manifest use the timestamp from when the download finishes.

---

3. Verification & Restoration

Q: How can I verify that my backup archive is complete and valid?

Use one of four verification methods:

1. Automated Inspection (mailsweep restore): Run the restore command in dry-run mode. The tool computes the SHA-256 digest, checks the .sha256 file, and parses manifest.json:

   mailsweep restore --backup backups/email_backup_<name>.zip
   

2. Search and Filter Within Backup:

   mailsweep restore --backup backups/email_backup_<name>.zip -q "Receipt"
   

3. Manual Checksum Verification in PowerShell:

   Get-FileHash backups\email_backup_<name>.zip -Algorithm SHA256
   Get-Content backups\email_backup_<name>.zip.sha256
   

4. ZIP Archive Inspection: Open the .zip archive in your system file manager to inspect raw .eml files sorted by folder. Standard email applications open .eml files directly.

---

4. Domain & Organization Protection (Tier 0)

Q: How does Tier 0 Automatic Protection work?

• Automatic Login Domain Discovery: MailSweep inspects your IMAP_USER setting. If the address uses a private domain instead of a public provider, the engine protects all domain emails from deletion.
• USER_DOMAINS (.env): Add private or workplace domains (for example, USER_DOMAINS=company.com,family.org) to protect messages from those domains.
• USER_ORGANIZATION_KEYWORDS (.env): Add keywords for your housing company, property manager, or personal organizations (for example, USER_ORGANIZATION_KEYWORDS=taloyhtio,housingcompany).

---

5. Email Counts & Folders

Q: Why is the scanned email count lower than the count in the Gmail interface?

MailSweep excludes folders like Sent Mail ([Google Mail]/Lähetetyt), Trash ([Google Mail]/Roskakori), and Drafts ([Google Mail]/Luonnokset). This exclusion protects outbound messages and drafts from modification. The difference between total web storage and the scan count reflects these excluded folders.

Q: Does MailSweep modify the IMAP_FOLDER configuration in .env?

No. MailSweep never writes to or alters your .env file.

• Automatic Folder Discovery: If you omit IMAP_FOLDER, MailSweep queries the server and scans all available folders except Trash, Sent, and Drafts.
• Restricted Scan Mode: If you specify folders manually (for example, IMAP_FOLDER=INBOX), MailSweep scans only those folders.

Q: How does MailSweep handle Gmail category folders and [Gmail]/All Mail?

• Category Folders: When Gmail uses category folders (such as [Gmail]/Categories/Promotions or [Gmail]/Luokat/Tarjoukset), MailSweep scans these folders.
• All Mail Discovery: When category folders are absent, MailSweep discovers and scans [Gmail]/All Mail directly.
• Message Deduplication: MailSweep identifies duplicate messages across folders using X-GM-MSGID or Message-ID. It merges labels across all mailbox views into a single EmailHeader.

---

6. Attachment Handling & Batch Sizes

Q: How does MailSweep process large emails and attachments?

MailSweep dynamically adjusts batch sizes based on message size:

• It downloads lightweight emails (<5MB) in batches of 50 messages.
• It isolates large emails (>5MB) and downloads them individually to avoid network timeouts.
• If the server rejects a batch request, the tool automatically fetches items one by one.

---

7. Multi-Client & Server Synchronization Safety

Q: What happens if another client deletes emails while MailSweep is running?

MailSweep tracks IMAP UIDVALIDITY values and immutable message UIDs:

• If the server re-indexes or changes a folder between scan and execution, MailSweep detects the UIDVALIDITY change and aborts before modifying messages.
• MailSweep uses RFC 4315 UIDPLUS targeted expunge (UID EXPUNGE <seq>). It expunges only planned clutter messages and preserves messages deleted by other clients.

---

8. Installation & Binary Execution

Q: How do I install and execute MailSweep?

You can install and run MailSweep in two ways:

• Download Pre-Compiled Binary (Recommended): Download the standalone release archive for Linux (x86_64, aarch64) or Windows (x86_64) from MailSweep Releases, extract the archive, and run mailsweep <command> directly.
• Build from Source (Cargo):
  • Build release binary: cargo build --release
  • Run commands directly: mailsweep <command> (or cargo run -- <command>)
  • Install binary to Cargo bin path: cargo install --path .

---

9. Batch Metrics & Progress Logs

Q: How does MailSweep calculate batch timing and progress metrics?

During backup and cleanup runs, MailSweep outputs progress lines such as:

[00:16:45] [4050/18226 (22.2%)] Processed in 'INBOX' (1.10s, 50 saved)

• [00:16:45]: Local time when the batch completed.
• [4050/18226 (22.2%)]: Overall progress across all folders.
• (1.10s, 50 saved): Elapsed time for the IMAP server roundtrip, streaming transfer, and disk write for that 50-email chunk.

---

10. Mailbox Trash & 30-Day Recovery Window

Q: Does MailSweep permanently delete emails from the server immediately?

No. MailSweep moves clutter to your server's Trash or Deleted Items folder by default.

• Moved messages remain in your server Trash for 30 days under standard retention policies.
• You can restore emails through your webmail client or use mailsweep restore with your offline backup archive.

---

11. Non-ASCII Folder Names & IMAP Modified UTF-7

Q: Why do folder names appear as [Google Mail]/T&AOQ-hdell&AOQ- merkityt in raw server logs?

Under the RFC 3501 Section 5.1.3 specification, IMAP servers encode non-ASCII folder names using Modified UTF-7:

• Characters such as ä, ö, å, and é are encoded in base64 UTF-16BE between & and -.
• For example, ä becomes &AOQ-.
• The folder Tähdellä merkityt transmits over the wire as T&AOQ-hdell&AOQ- merkityt.
• The folder Tärkeää transmits as T&AOQ-rke&AOQA5A-.

MailSweep uses an RFC 3501 codec (decode_imap_utf7) to convert these wire strings into readable UTF-8 for console output and reports.

---

12. Rules Engine, Upstream Sync & Manifests

Q: Where are upstream rule feed URLs configured?

Upstream rule feeds are configured in sources.json in the project root. This manifest declares remote feeds across several formats:

• Apache SpamAssassin .cf rules
• Rspamd .lua classification modules
• IETF RFC standard documents (for example, RFC 8058 and RFC 6154)

Q: What is the difference between --sync-sources and --sync-upstream in mailsweep rules?

• --sync-sources (Recommended for external feeds): Reads sources.json and downloads all enabled feeds. It parses external formats, merges keywords into rules.json, validates all 13 languages, and creates a backup file.
• --sync-upstream (Single endpoint replacement): Downloads a complete rules.json file from a single remote URL (such as --source https://example.com/rules.json), validates the schema, and replaces local rules.json.

Q: Does MailSweep connect to external upstream rule feeds on every run?

No. All rule validation (mailsweep rules --check), pipeline execution (mailsweep sweep), and unit tests (mailsweep test) run 100% offline. MailSweep contacts external repositories only when you explicitly run mailsweep rules --sync-sources or mailsweep rules --sync-upstream.