imapsync: How to Use It for Email Migration (Safe Flags, Folders, and Verification)

 

If you are reading this, you are likely staring at a migration project that makes you nervous. You need to move email from Server A to Server B. You cannot lose data. You cannot break the folder structure. And you certainly do not want to pay a $15/user "migration license" fee to a third-party vendor just to move bytes you already own.

You are looking for imapsync.

imapsync is the industry standard, command-line utility for synchronizing mailboxes between two IMAP servers. It is not a simple "copy-paste" tool; it is a state-aware synchronization engine. It tracks what has moved, handles network interruptions, and ensures that your "Sent Items" actually end up in the "Sent" folder, not a new folder called "Sent Messages."

But it is a sharp tool. Used without understanding the physics of the IMAP protocol, you can duplicate gigabytes of data, trigger "bandwidth bans" from Google, or accidentally wipe a destination mailbox.

This guide is your safety manual. We are going to walk through the architecture of a safe migration, the specific flags you need to avoid disaster, and how to verify that every single email made it across.

Whether you are a founder moving a single domain to save on Google Workspace costs, or an MSP managing 500 seats, this is the operator's guide to a zero-loss migration.

---

What imapsync is good at (and what it isn't)

Before you open your terminal, you must understand what you are working with. imapsync is a single-threaded Perl script that acts as a proxy. It connects to Host1 (Source) and Host2 (Destination) simultaneously. It reads messages from the source and appends them to the destination.

It is not a backup tool. It is not an SMTP relay. It is a synchronization tool.

The "State Preservation" Layer

A successful migration isn't just about moving text. It's about preserving three layers of data:

1. Content: The RFC 822 message body, attachments, and MIME encoding.
2. Metadata: The flags. You need to know if an email was \Seen (Read), \Answered (Replied to), or \Flagged (Starred).
3. Structure: The folder hierarchy. INBOX/Clients/ProjectA must look exactly the same on the new server.

imapsync handles all three, provided you configure it correctly.

The Hard Limits (What it won't do)

• Email Only: It speaks IMAP. It cannot see your Google Calendar, your Outlook Contacts, or your Exchange Transport Rules. For a full guide on the limitations of the protocol, see our IMAP Migration: How It Works and How to Migrate Mailboxes Safely.
• No "Push": It pulls data. If your source server is offline or firewalled, imapsync cannot reach it.
• Throttling: It does not inherently know the API limits of Gmail or Office 365. If you run it full throttle, you will get your IP banned. You have to tell it to slow down.

A Note for the Smart Operator:
If the idea of managing Perl dependencies, compiling CLI tools, and calculating TCP keepalives sounds like a headache you don't have time for, there is an alternative. TrekMail offers a built-in migration tool that handles this logic for you. Whether you have 5 users or 500, paying per-seat adds up. TrekMail's pooled storage model eliminates this cost and the migration complexity in one go.

---

Phase 1: The Forensic Discovery (Don't Skip This)

Amateurs just start copying. Professionals audit the environment first. If you don't know what you are moving, you will fail.

1. Identify the "Whales"

You likely have a user with a 45GB mailbox. If you try to migrate them in the same batch as your 500MB users, your batch will stall.

• Action: Run a pre-scan to get folder sizes.
• Command: imapsync ... --dry --justfoldersizes
• Why: Identify mailboxes larger than 10GB. These need special handling (longer timeouts, dedicated run times).

2. The "Dark Data"

Every company has "zombie" accounts. Ex-employees whose email is still being forwarded. "Service Accounts" that are actually shared inboxes for a printer or a legacy app.

• Risk: If you miss these during the inventory, that data is stranded when you cut the DNS.
• Fix: Audit your source user list against your payroll list. If bob@company.com left three years ago, do you need to migrate him, or just archive him to a PST?

3. The Item Count Truth

Never trust the size in Gigabytes.
Source Server A might report a mailbox is 10GB. Destination Server B might report it as 11GB.

• Why: Different servers calculate storage differently. Exchange includes the "Dumpster" (Recoverable Items). Gmail dedupes messages across labels.
• The Golden Metric: Item Count. If the source has 14,200 items and the destination has 14,200 items, you are good. Ignore the byte variance unless it's massive (>10%).

---

Phase 2: The Safe Migration Workflow

The biggest mistake rookies make is the "Big Bang" migration—trying to move everything on Friday night. If you have 50GB of mail and a 500KB/s throttle limit, the math doesn't work. You will be down on Monday morning.

The professional approach is the Staged Migration.

Step 1: The Dry Run (Verification)

First, verify you can connect without moving a single byte. Use the --dry flag. This tells imapsync to simulate the run and report what would happen.

imapsync --host1 imap.gmail.com --user1 user@source.com --passfile1 /secret/pass1 \

         --host2 imap.trekmail.net --user2 user@dest.com --passfile2 /secret/pass2 \

         --dry --justfolders

 

What to look for:

• Authentication: Did it log in?
• Folder Names: Do you see [Gmail]/Sent Mail on the source and Sent Items on the destination? You will need to map these (more on that in Section 4).

Step 2: The Bulk Sync (Pre-Stage)

Run this while the user is still working on the old system. This happens 1-2 weeks before your deadline.

The Strategy: Move the heavy lifting out of the critical path.
The Command:

imapsync ... --usecache --skipsize --maxsize 25000000

 

• --usecache: This is mandatory. It saves the state of the migration locally. When you run the tool again, it won't re-check every single email; it will only look for changes.
• --maxsize 25000000: We skip messages larger than 25MB in the first pass. Large attachments are the most likely cause of timeouts and connection drops. We will catch them later.

Step 3: The Delta Sync (The "Catch Up")

A few days before the switch, run it again. Because we used --usecache, imapsync compares the source and destination. It sees that 10,000 emails are already there and skips them, only copying the 50 new emails that arrived since Step 2.

Step 4: The Cutover (Final Delta)

This is the danger zone. You are switching the flow of mail.

1. Lower DNS TTL: 48 hours before the switch, set your MX record TTL (Time To Live) to 300 seconds. This ensures the internet notices your change in 5 minutes, not 24 hours.
2. Switch MX Records: Point them to TrekMail (or your new host).
3. Wait: Wait 1 hour for propagation.
4. Run Final Delta: Run imapsync one last time to catch the stragglers that landed on the old server while DNS was updating.

For a full guide on managing DNS during this window, see Email Migration: The Step-by-Step Guide to Move Mail Without Losing Emails or Downtime (2026).

---

Phase 3: Flags, Folders, and The "Sent" Trap

IMAP servers speak different dialects. If you don't translate between them, your users will wake up to a mess.

1. The Delimiter Problem (Dot vs. Slash)

This is the most common technical failure.

• Server A (Dovecot): Uses a dot separator. INBOX.Clients.ProjectA
• Server B (Exchange): Uses a slash separator. INBOX/Clients/ProjectA

If you migrate blindly, imapsync might create a folder on Server B literally named INBOX.Clients.ProjectA—a single folder with dots in the name, rather than a nested structure.

• The Fix: Use --regextrans2 to rewrite the paths on the fly.
• Agency Note: Always test folder creation with --dry on a test account before running a batch of 100 users.

2. The "Sent Items" Chaos

Every server names the Sent folder differently.

• Gmail: [Gmail]/Sent Mail
• Outlook/Exchange: Sent Items
• cPanel/Courier: Sent
• Localized: Gesendete Elemente (German), Enviados (Spanish)

If you don't map these, your user will have two sent folders: their active one (Sent Items), and a new archive folder named Sent Mail containing their history. They will hate this.

The Fix: Map the folders explicitly.

--regextrans2 's/^\[Gmail\]\/Sent Mail/Sent Items/'

 

This command tells imapsync: "If you see a folder starting with [Gmail]/Sent Mail, rename it to Sent Items on the destination."

3. The Gmail "All Mail" Trap

Gmail is unique. It has a folder called [Gmail]/All Mail that contains a copy of every single email, regardless of its label.

• The Risk: If you migrate All Mail AND Inbox AND Sent, you will duplicate every email three times on the destination server. A 10GB mailbox becomes 30GB.
• The Fix: Always exclude All Mail.

--exclude "All Mail"

 

---

Phase 4: Performance Tuning (Throttling & Timeouts)

You cannot just blast data at Google or Microsoft. They have sophisticated defense systems designed to stop Denial of Service (DoS) attacks. A migration looks exactly like a DoS attack.

The "Penalty Box"

If you exceed the rate limits (usually around 1 message per second or 500MB per hour), the server will start returning HTTP 429 or BAD errors. If you keep pushing, they will lock the account for 24 hours.

The Tuning Flags:

• --maxmessagespersecond 1: This is your speed limit. 1 email per second is safe. It seems slow, but it is steady.
• --maxbytespersecond 500000: Caps bandwidth at 500KB/s.
• --timeout 120: Increases the network timeout. Default is often too short for large attachments.

Operator Tip:
If you are migrating to TrekMail, our infrastructure is built to handle high-concurrency IMAP ingestion. You can be more aggressive with us than you can with Microsoft 365.

---

Phase 5: Authentication (The Modern Auth Hurdle)

The days of putting password123 in a text file are over.

1. Basic Auth is Dead

Google and Microsoft have deprecated "Basic Auth" (username/password) for IMAP. If you try to use your standard login, it will fail.

2. The Solution: App Passwords

For most SMB migrations, the easiest path is App Passwords.

1. Log into the source account (e.g., Gmail).
2. Enable 2-Factor Authentication (2FA).
3. Go to Security settings and generate an "App Password" (sometimes called "App Specific Password").
4. Use that 16-character string as the password in your imapsync script.

3. The Enterprise Path: OAuth2

If you are an MSP migrating 500 users, you cannot generate 500 App Passwords manually. You need OAuth2.
This requires:

• Registering an Application in the source tenant (Azure AD or Google Cloud Console).
• Granting that application "Full Access" to all mailboxes.
• Generating a Refresh Token.
• Passing that token to imapsync via --oauthaccesstoken1.

This is complex. If you mess up the permissions, you open a security hole in the client's tenant.

---

Phase 6: Common Failure Modes & Recovery

Even with a perfect plan, things break. Here is how to read the error logs.

1. The "Bridge Issue" (UIDVALIDITY)

This is the nightmare scenario.
IMAP folders have a unique ID called UIDVALIDITY. If a folder on the source server is deleted and recreated (or if the server index corrupts and rebuilds), this ID changes.

• The Symptom: imapsync looks at the folder, sees a new ID, assumes it is a brand new folder, and re-downloads everything. You now have duplicates of every single email.
• The Fix: If you suspect this happened, delete the local cache files in your temp directory. Then, run the sync with --useheader.
• --useheader: This forces imapsync to compare the Message-ID header of every email (which is immutable) rather than relying on the folder ID. It is slower, but it is duplicate-proof.

2. Corrupt & Zero-Byte Messages

Sometimes, a legacy server has "ghost" messages—headers with no body, or files with 0 bytes.

• The Symptom: imapsync tries to fetch the message, the server hangs, and the connection times out.
• The Fix: Use --minbytes 10. This tells the tool to ignore any message smaller than 10 bytes (which is effectively an empty file).

3. The "Zombie" Data (Deletes not syncing)

You ran a sync on Monday. On Tuesday, the user deleted 50 emails on the source. On Wednesday, you run the sync again.

• The Issue: By default, imapsync adds new mail. It does not delete mail on the destination that was deleted on the source. This is a safety feature.
• The Result: The user sees the 50 deleted emails reappear in their new mailbox.
• The Fix: Use --delete2.
• WARNING: --delete2 tells imapsync: "If it's not on the source, DELETE it from the destination."
• DANGER: Do not run this after the cutover. If new mail has arrived on the destination, --delete2 will wipe it out because it doesn't exist on the old source. Only use this during the pre-stage phase.

---

Verification: How to Prove It Worked

You are done. The script finished. How do you know you didn't lose the CEO's emails?

1. The Summary Log
Look at the final output block:

• Transferred: Should be 0 (on the final run).
• Skipped: Should match the total count.
• Errors: Should be 0.

2. The Spot Check
Log into the new mailbox.

• Check the Sent Items. Are they there?
• Check a subfolder. Is the structure correct?
• Check the most recent email.

3. The Forensic Search
If a user claims "I'm missing an email from Bob," use grep on the imapsync log file.

grep "Bob" /var/log/imapsync/user.log

 

The log will tell you exactly what happened to that message: Transferred, Skipped (already there), or Error.

---

Conclusion

imapsync is the most powerful tool in the migration arsenal because it gives you total visibility. It doesn't hide behind a progress bar; it tells you exactly what is happening to every single byte of data.

But it requires patience, precision, and a willingness to get your hands dirty with CLI flags and error codes.

The TrekMail Alternative
We wrote this guide because we believe in transparency. But we also know that for many Operators, the time cost of configuring Perl scripts, managing OAuth tokens, and babysitting throttling limits outweighs the software savings.

That is why we built TrekMail.
We designed TrekMail for the Smart Operator who values their time. We provide professional email hosting with flat-rate pricing (no per-user tax) and a built-in migration engine that handles the heavy lifting for you. You get the power of a professional migration without the terminal window.

Whether you choose to script it yourself or use our platform, the goal is the same: professional email, under your control.

Ready to stop paying per-user fees? Check out TrekMail and take back control of your infrastructure.