Independent / migration and recovery

MailSync

Explain every mailbox decision before making it irreversible.

01 / Purpose

Purpose and scope.

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.

Run explainable one-way mailbox migrations between IMAP servers.

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 / Interactive demo

MailSync: understand a migration plan.

Open a saved job or create your own sample. Check its fixtures, inspect folder mappings, then run a sample inspection and review the decisions and logs.

About this demoAn interactive local preview using fictional data, embedded in this portfolio. Jobs, mailbox setup and the Run, Folders and Logs screens are adapted from MailSync. The decision inspector explains its planning rules. Connections and progress use bundled fixtures; no mailbox is connected and no mail is moved. Changes reset when you reload.

MailSync / Local workspace reconstruction · fictional mailboxes

All Jobs

Open, edit, and continue saved mailbox jobs.

All Jobs

Completed means a sample inspection finished, not that mail was migrated.

Search Jobs

2 matching jobs

Sort

JobDetailsStateActions

Studio mailbox moveOne-way migrationstudio@source.example → destination@target.example

Inspected: 6 / 6Changes applied: None

Needs attention

Archive transferOne-way migrationarchive@source.example → destination@target.example

Inspected: 3 / 3Changes applied: None

Completed

Jobs, setup, Run, Folders and Logs follow MailSync’s interface. Sample connection checks, progress and decisions run in browser memory. No IMAP, credentials, migration apply, backup or recovery operation is available.

03 / Decisions

Engineering decisions.

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.

04 / Architecture

How it works.

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.

05 / Technology

The working parts.

PythonIMAPSMTPMariaDB / MySQLSQLiteFernet encryptionServer-rendered web UICLI

06 / Project status & roadmap

Current state and next steps.

Current

The hardened one-way migration path is a release candidate, verified in local testing.
406 automated tests pass, with three skipped for environment-specific reasons.
Saved jobs, owner-scoped workspaces, logs, backups and run controls exist in the persistent application.
Two-way sync can plan changes; applying them is deliberately switched off for now.

Planned

A first controlled run on real mailboxes, plus a live MariaDB integration test.
Bring the same crash-safe copy protocol to two-way sync.
Finish bulk-migration preflight, queues, scheduling and exportable reporting.
Add provider presets, OAuth, throttling profiles and resumable runs.