imapsync Explained: The Two-Pass Method for IMAP Migration

An IMAP migration tool moves mail from one IMAP account to another over the wire, folder by folder, message by message, without touching the sending server or anything else sitting in the receiving server. Sysadmins reach for imapsync by default, and for good reason: it's free, it's command line, it's been battered by years of real-world use, and you can run it more than once against the same pair of accounts without duplicating a thing. That last property is the whole reason a sane migration plan exists in the first place.

What is imapsync and what does it actually do?

imapsync is a command line utility that connects to two IMAP servers at once, source and destination, and copies mail from one to the other. It reads the folder structure and message flags on the source account and rebuilds them on the destination. It doesn't care what software either server runs. Dovecot to Exchange, cPanel to Google Workspace, one Zimbra box to another, none of it matters as long as both ends speak IMAP properly, as defined in RFC 3501.

What does imapsync not do?

This is the bit people skip, and then lose an afternoon over. imapsync moves mail. That's it. It doesn't touch calendars, doesn't touch contacts, doesn't touch client side rules or server side filters, and it won't migrate shared mailboxes as one single operation, you run it per mailbox instead. If a client asks you to "move everything" and everything includes a shared calendar and a contacts book, imapsync gets you the mail and you'll need a separate plan for the rest. Say this out loud on the discovery call. It saves an argument later.

Why is idempotency the whole point?

Idempotency matters because it means you can run the same sync job twice, or ten times, and it won't create duplicate messages on the second go. imapsync checks what's already sitting on the destination before it copies anything, so a repeat run only picks up what's new or changed. Most migration tools can't make this promise. That single property is what turns a risky one shot migration into a controlled, repeatable process, and it's why imapsync has stuck around as the standard tool for this job rather than getting replaced by something shinier.

How does the two-pass migration pattern work in practice?

Run a full sync days before cutover, while the old mailbox is still live and mail is still arriving there. This copies the bulk of it, historic mail, big attachments, years of folders, with no time pressure at all. Nothing about this first pass is urgent, because the source account keeps working normally the whole time.

Then, right after the MX record switches over and new mail starts landing at the destination, run the sync a second time. Because imapsync is idempotent, this pass only pulls across whatever arrived on the source between the first run and cutover, the messages that came in during propagation. Two passes, not one, is the difference between a clean migration and a client emailing you three days later asking where last Tuesday's invoices went. Check propagation with a quick MX lookup before you assume the switch has actually taken, and if you need the wider context on DNS behaviour during a cutover, read it up front rather than mid migration.

What goes wrong: the real-world friction points

Authentication is where most jobs stall. If the source account has two factor authentication switched on, the normal account password won't get you in, you need an app specific password generated for the job, and not every provider makes that easy to find. If the source has disabled basic authentication entirely and forces OAuth, imapsync needs setting up with OAuth tokens instead of a plain password, which is a different step and worth testing on a single mailbox before you commit the whole domain to it.

Gmail brings its own trap. Its All Mail folder is a virtual view of everything in the account, so syncing it alongside the regular folders means copying the same messages twice. Exclude All Mail explicitly and sync the real folders instead.

Folder naming and delimiters differ between server platforms too. One might use a forward slash to separate nested folders, another a dot, and "Sent Items" versus "Sent" won't map itself. Expect to remap a handful of folders by hand on the first run rather than assuming a like for like copy.

Message size limits on the destination server will silently reject anything over the cap, usually the odd message with a huge attachment, so check the logs rather than assume a clean run means a complete one. And large mailboxes, particularly on providers that throttle IMAP connections, can take a lot longer than the mailbox size suggests. A ten gigabyte mailbox on a server with aggressive rate limiting can drag on far longer than the same mailbox somewhere with none. Budget time by that, not by gigabyte count alone.

Before you commit to a migration window, run the account pairs through an email migration checker so authentication and size problems turn up before the job's underway, not halfway through it.

What does an imapsync command actually look like?

The core shape of an imapsync command specifies the source host and credentials, then the destination host and credentials. In placeholder form, it looks roughly like this:

imapsync --host1 mail.oldhost.example --user1 [email protected] --password1 'app-specific-password' --host2 mail.newhost.example --user2 [email protected] --password2 'destination-password'

From there you'll typically add flags to force encrypted connections on both ends, exclude specific folders such as Gmail's All Mail, and run a dry pass first that reports what would happen without actually moving anything. Flag names and options change between imapsync releases, so treat the official imapsync documentation as the authority on exact syntax, not this post or any other. If you're not sure a flag exists in the version you're running, check the docs before guessing, a malformed flag either errors out cleanly or, worse, gets quietly ignored.

Can you script imapsync for a whole domain migration?

Yes, and this is where it earns its keep on anything bigger than one mailbox. Because it's a command line tool with predictable arguments, you can build a plain text file listing every account pair, source address and password alongside destination address and password, one line per mailbox, then loop over that file calling imapsync once per line. A domain with two hundred mailboxes that would take a GUI tool days of clicking turns into a script that runs unattended overnight. This is also where the two-pass pattern pays off properly, because you run the same loop twice, once before cutover and once after, and idempotency means the second run only mops up the deltas across every account, not just one.

When should you use a different tool entirely?

The moment the scope includes calendars, contacts, or a shared mailbox that needs to move as a unit with its permissions intact, imapsync is the wrong tool for that part of the job. That's not a knock against it, it was built to do one thing, sync IMAP mail between two accounts, and it does that better than almost anything else out there. But calendars use different protocols entirely, contacts need their own export and import path, and shared mailbox permissions are a platform level concept a mail sync tool simply can't see. Plan for these separately rather than hoping imapsync will somehow cover them. For a broader view of what else is out there and where each tool fits, our roundup of email migration tools covers the options, and our migration checklist is worth working through before you touch a single command.

Frequently asked questions

Is imapsync free to use?

Yes, imapsync is free command line software, though the project also sells a paid desktop version with a graphical interface for anyone who'd rather not work from the terminal. The engine doing the actual syncing is the same either way.

Will imapsync migrate my email folder structure exactly?

Mostly, but not always automatically. imapsync replicates folders and their contents, but if the source and destination servers use different naming conventions or delimiters, some folders will need remapping by hand rather than a straight one to one copy.

How long does an imapsync migration take?

It depends far more on message count, attachment sizes, and how much the source server throttles connections than on raw mailbox size. A mailbox on a provider with tight rate limiting can take noticeably longer than an equivalent sized mailbox on a server with no such restriction, so test on a sample account before promising a client a specific window.

Can imapsync migrate shared mailboxes or distribution groups?

Not as a single operation. Each mailbox, shared or otherwise, has to be treated as its own source and destination pair. Permissions and access rules on a shared mailbox are a platform level setting that imapsync has no awareness of and can't replicate.

Final thoughts

imapsync remains the right default for IMAP to IMAP mail migration because it's honest about what it does and doesn't try to be more than that. Run the first pass early, run the second straight after the MX switch, and check your folder mappings and size limits before you call it done. The moment the job grows beyond mail into calendars, contacts, or shared mailbox structure, stop trying to make one tool cover everything and bring in something built for that part instead.