Copy the mailbox.
Keep its history.
An IMAP-to-IMAP migration engine with a command-line interface and a self-hosted web application.
Copy messages with their folders, internal dates and flags. Track each message in a ledger, identify mail already at the destination and continue an interrupted run from recorded progress.
A mailbox is more
than message text.
The engine sends the message to the destination using IMAP APPEND, passing its original internal date and flags. It copies the message data rather than forwarding it as a new email.
Folder mapping determines where each message belongs. The mapper includes special-folder mappings and configurable overrides; it also converts folder delimiters and removes an INBOX prefix for ordinary nested folders.
For example, with the default mapping, INBOX.Clients.Project becomes Clients/Project. The destination server and your chosen configuration determine the mapping you should actually use.
Each message has
a decision path.
The runner maps folders and scans headers. MessageMigrator handles the individual copy, while the ledger records its state. Those responsibilities are separate in the source.
- Check recorded progress.
A message already marked copied is skipped. Resumed scans use the highest recorded source UID to avoid reading the whole folder again.
- Check the destination.
On the initial folder scan, collect destination Message-IDs. An exact match is recorded as skipped rather than appended again.
- Read and append.
Fetch the source message, append it to the mapped destination folder with its date and flags, then record whether the append succeeded.
- Keep failure visible.
Unreadable content or a rejected append is recorded as failed. The engine can enforce a configured message-size limit before sending the message.
A terminal job.
Or a migration workspace.
The command-line entry point reads account configuration, connects both IMAP accounts and uses a local SQLite ledger. It reports copied, skipped, failed and would-copy totals.
The web application adds user accounts, jobs, a dashboard and a background worker. The repository includes a MySQL ledger implementation for that application.
Both routes give the copy work a recorded state. Choose the interface that fits how you intend to operate migrations.
Know what has moved.
Investigate what has not.
An interruption does not require starting every folder from scratch. The ledger records progress and the runner resumes scanning from recorded UIDs. A failed message still needs attention through the appropriate retry path.
The code stores a metadata hash when Message-ID is absent. The reviewed destination duplicate check compares Message-IDs; that is why this page does not promise that every possible duplicate will be detected.
Read the runner tests ↗Does it delete the source mailbox?
The migration engine copies from the source and appends to the destination. It does not perform the domain cutover or close the original mailbox. Those are separate operational decisions.
Does a dry run prove the copy will succeed?
No. It checks the discovery and duplicate-decision path without writing messages to the destination. A small real copy is still needed to check message acceptance and preservation.
What does the project require?
The current Composer manifest requires PHP 8.5 or newer, PDO and PDO SQLite. Dependencies include Webklex PHP IMAP; read the repository setup instructions for the CLI or web application you intend to run.
Can it move mail from my provider?
Both accounts need working IMAP access using an authentication method the client supports. Verify those connections and the folder mapping with your actual providers before scheduling a migration.
Start with the providers.
Then the migration plan.
Tell us the source and destination, account count, approximate mailbox sizes and transition deadline. We can scope implementation help separately from the open-source tool.
Discuss a migration ↗