How to migrate email with IMAPSync between servers without losing messages

Install Perl dependencies and build tools:

sudo apt update
sudo apt install -y \
  git make cpanminus libio-socket-ssl-perl libnet-ssleay-perl \
  libcrypt-ssleay-perl libmail-imapclient-perl libdigest-md5-file-perl \
  libdist-checkconflicts-perl libfile-copy-recursive-perl \
  libio-tee-perl libjson-webtoken-perl libreadonly-perl \
  libregexp-common-perl libsys-meminfo-perl libterm-readkey-perl \
  libtest-fatal-perl libtest-mockobject-perl libtest-pod-perl \
  libtest-requires-perl libtest-deep-perl libunicode-string-perl \
  liburi-perl libencode-imaputf7-perl libfile-tail-perl \
  libdata-uniqid-perl libproc-processtable-perl libtime-hires-perl

The list looks long but each module covers a real case — SSL, IMAP UTF-7 encoding, unique ID parsing, live log tailing. Skipping any of them will result in a cryptic error in the middle of the migration.

Clone and install IMAPSync:

git clone https://github.com/imapsync/imapsync.git
cd imapsync
sudo make install
imapsync --version

The final command should return something like Imapsync 2.255 or higher. If you see “Can’t locate … in @INC”, a Perl module is missing — identify the name from the error and install it via sudo cpanm Module::Name.

Create a migration.sh file with the account variables:

#!/bin/bash
imapsync \
  --host1 mail.source.com \
  --port1 993 \
  --ssl1 \
  --user1 [email protected] \
  --password1 'SOURCE_PASSWORD' \
  --host2 mail.destination.com \
  --port2 993 \
  --ssl2 \
  --user2 [email protected] \
  --password2 'DESTINATION_PASSWORD' \
  --dry \
  --justfolders

The --dry --justfolders combination lists folders on both sides without touching messages. It’s the quickest way to detect a mismatch (e.g., the source has “INBOX.Sent” and the destination expects “Sent Items”).

Run it and analyze the output:

chmod +x migration.sh
./migration.sh 2>&1 | tee dry-run.log

Look in the log for lines starting with Host1 folders: and Host2 folders:. If there’s a discrepancy (e.g., source uses dot hierarchy “INBOX.Work” and destination uses slash “INBOX/Work”), you’ll need --regextrans2 's,INBOX\.,INBOX/,g' on the real run.

Start a tmux session to run in the background:

tmux new -s migration

If the SSH connection drops, reconnect and run tmux attach -t migration to keep watching.

Run the full sync by removing --dry --justfolders:

imapsync \
  --host1 mail.source.com --port1 993 --ssl1 \
  --user1 [email protected] --password1 'SOURCE_PASSWORD' \
  --host2 mail.destination.com --port2 993 --ssl2 \
  --user2 [email protected] --password2 'DESTINATION_PASSWORD' \
  --automap \
  --syncinternaldates \
  --useuid \
  --addheader \
  --logfile LOG_imapsync/user.log

The --automap flag automatically maps Sent/Sent Items/INBOX.Sent between different providers. --syncinternaldates preserves the original date. --useuid makes the sync idempotent — running again won’t duplicate anything. --addheader adds X-Imapsync to messages so you can audit later which ones were migrated.

Lower the MX record TTL at the DNS provider to 300 seconds (5 min) BEFORE making any change — ideally 24h beforehand. This ensures fast propagation when you switch the destination. If the TTL was 3600 or 86400, everyone will keep seeing the old value until that time expires.

# Check current TTL before changing
dig +short mx domain.com
dig +nocmd +noall +answer mx domain.com

Switch the MX to the new server. In the DNS panel:

• Type: MX
• Priority: 10 (or whichever you use)
• Value: mail.destination.com. (with trailing dot)
• TTL: 300

Wait 5-10 minutes and confirm propagation:

dig +short mx domain.com @1.1.1.1
dig +short mx domain.com @8.8.8.8

Both should return the new MX. If one returns the old one, the resolver cache hasn’t expired yet — wait a few more minutes.

Run IMAPSync a second time — same command as Step 06. Because of --useuid, it will only copy messages that arrived at the source between the first and second run. Typically fast (2-10 minutes).

./migration.sh 2>&1 | tee LOG_imapsync/cutover.log

At the end of the log, look for Total bytes transferred. On a successful incremental sync, this value is small (a few MB at most).

Compare counts on source and destination:

imapsync \
  --host1 mail.source.com --port1 993 --ssl1 \
  --user1 [email protected] --password1 'SOURCE_PASSWORD' \
  --host2 mail.destination.com --port2 993 --ssl2 \
  --user2 [email protected] --password2 'DESTINATION_PASSWORD' \
  --justconnect

Then run with --dry to see the final report of counted messages in each folder on both sides:

./migration.sh --dry

At the end, look for Folder Host1/Host2 messages — each pair should match. A difference of ≤ 5 messages in a 10k+ folder is normal (messages that arrived between the last sync and the verification).