How to migrate email from the command line with imapsync

What imapsync does

Imapsync connects to a source IMAP mailbox and a destination IMAP mailbox, then copies folders and messages across. The official imapsync project describes it as an incremental command-line IMAP transfer tool, which means you can stop it and run it again without intentionally creating duplicates.

It does not migrate contacts, calendars, aliases, forwarders, DNS records, mailbox passwords, or mail client profiles. Plan those separately.

Before you run it

• Confirm both mailboxes exist and IMAP is enabled on both sides.
• Collect source and destination IMAP hostnames, usernames, passwords, and ports.
• Check mailbox quota on the destination before copying large accounts.
• Decide whether folders should keep their names or be mapped to different names.
• Lower DNS TTL before the final MX cutover if the mailbox provider is changing.

Single mailbox command

This is the basic shape of an imapsync command. Replace the hostnames, usernames, and passwords with your real source and destination values.

imapsync \
  --host1 old-mail.example.com \
  --user1 user@example.com \
  --password1 'SOURCE_PASSWORD' \
  --host2 new-mail.example.com \
  --user2 user@example.com \
  --password2 'DESTINATION_PASSWORD' \
  --ssl1 \
  --ssl2

If your shell saves command history, avoid typing real passwords directly into a shared terminal. Use temporary app passwords where possible, restrict access to the machine running the migration, and rotate credentials after the move.

Start with a dry run

A dry run proves authentication, folder discovery, and server reachability before moving mail.

imapsync \
  --host1 old-mail.example.com \
  --user1 user@example.com \
  --password1 'SOURCE_PASSWORD' \
  --host2 new-mail.example.com \
  --user2 user@example.com \
  --password2 'DESTINATION_PASSWORD' \
  --ssl1 \
  --ssl2 \
  --dry

Review the output for authentication failures, folder names, skipped messages, size limits, and server warnings. Fix those before running the real copy.

Copy folders first when the mailbox is complex

For large or messy mailboxes, it can help to create folders first, then run the full sync.

imapsync \
  --host1 old-mail.example.com \
  --user1 user@example.com \
  --password1 'SOURCE_PASSWORD' \
  --host2 new-mail.example.com \
  --user2 user@example.com \
  --password2 'DESTINATION_PASSWORD' \
  --ssl1 \
  --ssl2 \
  --justfolders

Run the first full sync

After the dry run succeeds, run the migration without --dry. For a large mailbox, use a terminal multiplexer such as screen or tmux so the job survives a dropped SSH session.

tmux new -s mail-migration

imapsync \
  --host1 old-mail.example.com \
  --user1 user@example.com \
  --password1 'SOURCE_PASSWORD' \
  --host2 new-mail.example.com \
  --user2 user@example.com \
  --password2 'DESTINATION_PASSWORD' \
  --ssl1 \
  --ssl2 \
  --automap \
  --logfile imapsync-user-example.log

The --automap option can help with common folder-name differences such as Sent, Trash, Drafts, and Junk. Always verify folder placement after the run, especially when moving between different providers.

Rerun before cutover

Run imapsync again shortly before changing MX records or moving the user to the new mailbox. The second pass should be faster because only new or changed messages need attention.

imapsync \
  --host1 old-mail.example.com \
  --user1 user@example.com \
  --password1 'SOURCE_PASSWORD' \
  --host2 new-mail.example.com \
  --user2 user@example.com \
  --password2 'DESTINATION_PASSWORD' \
  --ssl1 \
  --ssl2 \
  --automap \
  --logfile imapsync-user-example-final.log

Cutover checklist

• Confirm message counts and spot-check important folders in webmail.
• Update MX, SPF, DKIM, DMARC, autodiscover, and mail client settings as needed.
• Send test mail inbound and outbound from an external address.
• Keep the old mailbox available during the rollback window.
• Run one last imapsync pass after DNS has settled if mail continued arriving at the old host.

Bulk migrations

For multiple mailboxes, keep a CSV with source user, source password, destination user, and destination password, then loop over it from a shell script. Test with one low-risk mailbox before running the full batch, and throttle parallel jobs so the providers do not rate-limit or lock accounts.

Common failures

• IMAP is disabled or blocked by multi-factor authentication policy.
• The destination mailbox is too small for the source mailbox.
• Provider-specific folders map to unexpected destination folders.
• Large messages exceed the destination provider's message-size limit.
• Passwords contain shell-special characters and were not quoted correctly.

Need migration help?

Cyber Duct Tape can handle command-line imapsync migrations, DNS cutovers, cPanel mailbox moves, and post-migration email repair for Denver metro, Virginia Beach, and remote clients.