Run explainable one-way mailbox migrations between IMAP servers.
Independent / migration and recovery
MailSync
Explain every mailbox decision before making it irreversible.
01 / Purpose
A tool with a reason to exist.
A safety-first, self-hosted tool for migrating and synchronising IMAP mailboxes. MailSync combines reusable command-line workflows with a persistent web application for saved jobs, scoped workspaces, run controls, logs and backups.
Produce operator-readable COPY, SKIP, REVIEW and ERROR outcomes before apply.
Keep credentials, audit state and migration history under the operator’s control.
Recover safely when a remote append succeeds but local state is uncertain.
02 / Decisions
The interesting part is why.
Dry-run first
Mailbox changes are difficult to undo and ambiguous IMAP evidence should become review—not optimistic mutation.
Exact hashes
Message-ID alone can be absent, duplicated or misleading, so body evidence participates in identity.
Journal before side effects
The system must survive remote-success/local-commit ambiguity after a crash or disconnect.
One shared engine
The web application and CLI use the same planning and safety logic so the two interfaces cannot drift.
03 / Architecture
A deliberate path through the system.
Plan
Scan source and target mailboxes, bind the plan to their mailbox generations and classify every message.
→Explain
Use headers and exact content hashes to distinguish safe copies from ambiguous evidence that needs review.
→Journal
Persist a PREPARED attempt before the external mailbox mutation so interrupted work remains recoverable.
→Apply & verify
Append, require the target identifier, read the exact content back and only then commit mapping and state.
04 / Technology
The working parts.
PythonIMAPSMTPMariaDB / MySQLSQLiteFernet encryptionServer-rendered web UICLI
05 / State & roadmap
What is real now—and what comes next.
- The hardened one-way path is a locally verified stabilisation candidate.
- The current checkpoint records 406 passing tests with three environment-specific skips.
- Saved jobs, owner-scoped workspaces, logs, backups and run controls exist in the persistent application.
- Two-way planning exists, while message-copy apply remains deliberately blocked.
- Complete an approved live-mailbox canary and live MariaDB integration run.
- Extend the durable copy-attempt protocol to two-way message apply.
- Finish bulk-migration preflight, queues, scheduling and exportable reporting.
- Add provider presets, OAuth, throttling profiles and resumable-run UX.