Skip to content
postanex

Migration

Migrating Email Over IMAP: imapsync and Client Methods

Two ways to copy a mailbox between servers over IMAP: imapsync and client drag-and-drop. We compare them on size, time and verification, then give you a checklist.

Postanex Editorial Team · · 7 min read

A folder tree being copied between two mailboxes over an IMAP cable

Moving a mailbox from one server to another over IMAP is still the migration method with the fewest surprises. Whatever sits in the old mailbox gets copied into the new one with its folder structure intact. You need no export file and no special vendor tool, only a login on both sides.

Thunderbird, Outlook, Apple Mail, imapsync: they all speak the same protocol, yet they do not do the same job. The mistake we see most on migration projects is grabbing whichever tool is closest, then discovering three days later that the copy stopped halfway and nobody noticed.

Short answer: An IMAP migration connects to the source and destination mailboxes at the same time and copies folders and messages across. For a handful of small mailboxes, drag-and-drop in a mail client is fine. For many mailboxes, large volumes, or anything you want to rerun safely, use a server-side tool such as imapsync, and always compare message counts per folder before you call it done.

How IMAP migration works

An IMAP migration is a tool logging in to two servers, reading each message from one and appending it to the other. What moves is messages and folders, not files, so flags such as "read" or "answered" and the original date survive only if the tool is built to carry them.

The current protocol definition is RFC 9051, but three ideas matter in day-to-day work: the folder (mailbox) list, the per-folder message UID, and the Message-ID header that travels with each message. A decent tool does not copy the same message twice on a second run, because it can tell from Message-ID and date what already exists. That is what turns a migration from a one-shot gamble into something you can repeat.

Choosing a method: tool or client

If you have one or two mailboxes, a few gigabytes, and a laptop that can stay awake, a client is enough. For everything else, use a server-side tool.

Criterion Client (Thunderbird, Outlook) imapsync
Setup None, add the account twice Command line, a separate machine
Rerunning Manual, error-prone Same command, only missing mail copies
Many mailboxes Tedious Batch with a list file
Flags and dates Depends on the client Preserved
Error log Barely Detailed log

The hidden cost of the client route is time. You drag a folder across, the laptop sleeps, the connection drops, and you no longer know what made it. We do not forbid it for a small team. We just insist on checking the result with numbers.

imapsync for a single mailbox

This example copies an old hosting mailbox to a new server. Reading passwords from a file instead of typing them on the command line keeps them out of your shell history.

imapsync \
  --host1 mail.oldhost.example --user1 ayse@example.com \
  --passfile1 /root/p1.txt --ssl1 \
  --host2 imap.newserver.example --user2 ayse@example.com \
  --passfile2 /root/p2.txt --ssl2 \
  --automap --dry

--dry writes nothing and only shows what would happen, so make it your first run every time. The output lists folder mappings and how many messages would move. If it looks sane, remove --dry. --automap tries to pair special folders such as Sent, Drafts and Trash even when the two servers name them differently; still, read the mapping by eye.

Preparation: app passwords and permissions

A day before the move, settle how each account will authenticate. On Gmail and Microsoft 365 a normal password often will not work. Gmail with two-step verification needs an app password or OAuth, and Microsoft 365 has basic authentication turned off, so the connection has to use OAuth. Migrations that skip this step usually die in the first minute with AUTHENTICATIONFAILED.

Our short checklist: is IMAP enabled on the source, does the destination mailbox already exist, is there enough quota, and who actually knows the passwords? Where an administrator can log in on behalf of users, that is the easiest path. Where not, collect a one-time or app password from each person. If you are leaving a web host, our guide to migrating cPanel mailboxes covers the hosting-side traps separately.

Size, speed and limits

What decides the duration is rarely your bandwidth. It is the connection rate and daily download allowance the source server gives you. Large providers cap how much data one account may pull per day, and when you hit the cap the connection slows or gets refused. Do not fight it. Spread the job over several days.

Some habits that help:

  • For messages with huge attachments, set an upper bound with --maxsize and move those separately by hand.
  • Copy the last year first with --maxage 365, let people start working, and let the older archive trail in behind.
  • Avoid running many mailboxes in parallel. The source may drop connections, which looks like "running but never finishing".

When to switch MX is a separate question. To avoid missing mail that arrives mid-migration, follow the order in our zero-downtime email migration plan with MX and TTL.

Verification: counts and spot checks

"No errors" is not the same as "done". For every folder, the message count on the source and destination should match. imapsync summarises this at the end of its log. If you used a client, open both accounts side by side and compare at least the five largest folders.

Counts are not enough, so also spot-check. Open an old message, look at its date, download an attachment. A common failure is a tool that rewrites dates, leaving every message stamped with today. If you are coming from Gmail, remember that labels show up as folders and one message can appear in several of them, inflating the totals; the Gmail to business email migration article explains that difference in detail.

Do not delete the source until the check passes, and keep a copy. This is a good moment to look at how to back up company mailboxes.

Troubleshooting

The three situations we meet most: authentication failures, timeouts, and "could not create folder". The first is a password or OAuth problem, the second a rate limit or firewall, the third usually special characters or a different hierarchy separator (/ versus .) in folder names. --automap and --regextrans2 help with that last case. If you are leaving Microsoft, see migrating out of Microsoft 365 for extra differences.

Localised folder names are another quiet trap. A folder called "Gönderilmiş Öğeler" may be encoded differently by different servers, and if the output shows two separate "Sent" folders, the job is only half done.

Frequently asked questions

Does an IMAP migration delete mail from the old server?

By default it copies and leaves the source alone. Deletion starts only if you pass flags such as --delete1, so avoid them until verification is finished.

What happens to new mail while the migration runs?

As long as the MX record has not changed, new mail keeps landing on the old server. After you switch MX, run imapsync once more and the gap is filled on the destination.

Are calendars and contacts moved over IMAP?

No. IMAP carries mail only. Calendars and contacts move separately, through CalDAV/CardDAV or export files.

When is a client enough for migration?

One or two mailboxes, a few gigabytes, and a day when the computer can stay on. Beyond that, a server-side tool is safer for both repeatability and logging.

  • IMAP
  • imapsync
  • email migration
  • mailbox

Migration

Moving Off Hosting Email: Migrate cPanel Mailboxes

How to separate email from a web hosting bundle without touching the website: telling DNS records apart, inventory, copying mail, the MX cutover and the cleanup afterwards.

· 8 min read