IMAP Migration: The Universal Email Move

You inherited a mail server nobody documented, the vendor stopped answering tickets, and you have two weeks to get 400 mailboxes onto something modern. The good news: every serious mail platform speaks IMAP, and IMAP is the one protocol that lets you move messages between systems that otherwise share nothing. This guide walks through what an IMAP migration actually does, where it quietly fails, and how to plan one that finishes on schedule with intact folder trees and clean read/unread state.

Why IMAP is the lingua franca of email migrations#

Every modern mail platform — Exchange, Microsoft 365, Google Workspace, Zoho, iCloud, cPanel, Dovecot, Courier, Postfix-plus-anything — exposes an IMAP interface, even when their primary protocol is something else. Microsoft 365 prefers EWS or Microsoft Graph internally. Google prefers Gmail API. But both still answer on port 993 with a standards-compliant IMAP4rev1 listener, and that means you can read messages out of one and write them into another without either platform having to know the other exists.

That property — neutrality — is what makes IMAP the default migration protocol. When you migrate Gmail to Outlook, or Yahoo to Fastmail, or some self-hosted Dovecot box to Microsoft 365, you are almost certainly doing an IMAP-to-IMAP move regardless of what the marketing page says. The destination's "import from Gmail" wizard is usually just a hosted IMAP client pointed at imap.gmail.com.

This also means the failure modes are remarkably consistent. The same throttling errors, the same TLS issues, the same folder-naming quirks recur across providers. Once you understand IMAP migration in the abstract, every specific provider pair becomes a variation on a known pattern. For the broader migration context that sits around this — DNS, change management, user comms — start with the complete email migration guide.

What IMAP can and cannot move#

IMAP was designed in 1986 to let mail clients read messages from a remote server. It was never designed as a migration protocol. That history shows up in what it does and doesn't preserve.

What IMAP carries cleanly#

• Message bodies — the full RFC 5322 message including headers, body, attachments, and any MIME parts.
• Folder hierarchy — both at the top level (Inbox, Sent, Drafts, custom folders) and nested folders, subject to destination naming rules.
• Read/unread state via the \Seen flag.
• Star/flag state via \Flagged and (sometimes) Gmail labels mapped through IMAP folders.
• Internal date — the date the source server received the message, used for sorting and retention. Most tools preserve this via the APPEND command's INTERNALDATE argument.
• Custom IMAP keywords in providers that support them (Dovecot, Cyrus). Microsoft 365 and Gmail flatten these.

What IMAP cannot move#

• Calendars and appointments — these live in CalDAV or EWS, not IMAP.
• Contacts and address books — CardDAV or vendor-specific APIs.
• Server-side rules and filters — vendor APIs (Microsoft Graph, Gmail API) or no API at all.
• Out-of-office / vacation responder — varies wildly by platform.
• Distribution lists, shared mailboxes, delegated permissions — all administrative, not user-visible IMAP data.
• Signatures stored client-side — they're in Outlook profiles, browser settings, or Gmail's settings panel.
• Email aliases and forwarding rules — administrative, not in the mailbox.

Connection security: TLS, ports, and the things that go wrong#

Modern IMAP runs on port 993 with TLS from the first byte (IMAPS). Older deployments sometimes use port 143 with STARTTLS upgrade. You should be testing for both during discovery — and treating any pure plaintext IMAP as a security finding, not a migration option.

What to validate before you start#

Open a terminal and confirm the source server actually answers on 993 with a valid certificate. openssl s_client -connect imap.example.com:993 -servername imap.example.com is the standard one-liner. If you see a self-signed certificate, an expired cert, or a wildcard that doesn't match the hostname, your migration tool will refuse the connection until you either fix the cert or explicitly tell the tool to accept it.

The same check matters for the destination. Microsoft 365 and Gmail both serve well-formed certificates, but custom IMAP destinations (your new Dovecot box, a hosted IMAP provider you're moving to) frequently ship with default configurations that need attention. A failed handshake at the start of a 400-mailbox run is much cheaper than at the end.

Common TLS failure modes#

• STARTTLS handshake failed — the server advertises STARTTLS in its CAPABILITY list but the upgrade fails. Usually a TLS version mismatch (the server only supports TLS 1.0/1.1, your tool requires 1.2+).
• Certificate verify failed — self-signed or expired cert on the source. Either get a real cert or add the source CA to your trust store.
• SSL routines:tls_process_server_certificate:certificate verify failed — the hostname doesn't match the certificate's subject. Common with IP-based connections to old servers.

For a focused walkthrough of these, see fix TLS handshake failure.

Authentication patterns#

Authentication is where most IMAP migrations stall before they begin. Three patterns dominate, and which one applies depends entirely on the source and destination.

Basic auth (username + password)#

The original IMAP authentication: send the password over the wire, hope it works. Still used by cPanel hosts, smaller webmail providers, and self-hosted Dovecot. Simple to configure, but the password lives in your migration tool's credential store for the duration of the run. Use it where you must — and rotate the password immediately after the migration.

App-specific passwords#

Used by Yahoo, iCloud, Fastmail, AOL, and most providers that have MFA but no OAuth. The user (or admin, if there's a delegation path) generates a 16-character single-purpose password through the account's security settings. It bypasses MFA but is otherwise treated like a regular password by the IMAP server.

App passwords are the path of least resistance for any provider that supports them. They're revocable independently of the main account password, so cleanup is one click after the migration completes.

OAuth 2.0 (XOAUTH2)#

Used by Gmail, Microsoft 365, and a handful of others. The migration tool gets an access token and a refresh token by sending the user (or an admin acting on behalf of users) through a browser consent flow. The token gets included in the IMAP AUTHENTICATE XOAUTH2 command instead of a password.

OAuth is the only sensible choice for Gmail and Microsoft 365 today. Microsoft deprecated basic auth for IMAP in M365 in 2022, and Google followed for personal Gmail accounts. Workspace admins can still enable basic auth for migration windows, but it's a temporary workaround, not a strategy.

Throttling: the thing that decides your timeline#

You can have a 10 Gbps uplink and it will not help. IMAP migration speed is dictated by provider throttling — connection limits, per-second command limits, daily bandwidth caps, and sometimes opaque "we noticed unusual activity" cooldowns.

Throttling by provider class#

Different platforms throttle very differently, and you need to plan concurrency around the strictest one in the path.

Microsoft 365 historically allowed 20 concurrent IMAP connections per mailbox and a tenant-wide concurrent connection cap. In practice you'll hit Throttling: Server is throttling this request long before you saturate the per-mailbox limit when you're running 30 mailboxes in parallel.

Google Workspace allows up to 15 concurrent IMAP connections per account and has a daily bandwidth cap that's generous for normal use but visible during bulk migration. Use the Gmail API for the heavy lifting if you can; IMAP is the fallback.

Yahoo, AOL, iCloud, Fastmail typically allow 5–10 concurrent connections per account. Yahoo in particular is aggressive about flagging migration traffic and will lock accounts that look like brute-force attempts. Slow down before they decide for you.

cPanel / shared hosting is the unpredictable one. Limits depend on the host's Dovecot configuration. Some hosts cap at 5 connections per account and 50 from a single IP. Others have no limits and will happily let you DOS them. Test with one mailbox first. For a deeper look at this class, the cPanel to Microsoft 365 and cPanel to Gmail walkthroughs cover the specifics.

Self-hosted IMAP has whatever limits the operator configured. Often none, which is its own problem if the box is undersized.

Errors you'll see, and what they mean#

• Too many simultaneous connections — exactly what it sounds like. Reduce per-mailbox concurrency, then per-IP concurrency. The too many IMAP connections fix covers the patterns.
• Throttled / Service Unavailable (HTTP 503 in API responses) — provider-side rate limit. Back off exponentially.
• AUTHENTICATIONFAILED after a series of successful logins — provider has decided your IP looks suspicious. Pause, wait 30 minutes, resume from a different IP if possible.
• Message too large for destination — usually a 25–35 MB attachment hitting Microsoft 365's default size limit. Handle separately; don't let it kill the whole run. The broader pattern is documented in IMAP throttling errors.

Planning concurrency#

Start with two numbers: connections per mailbox (usually 3–5) and total concurrent mailboxes (usually 10–30). Multiply them. If the product exceeds the source provider's per-IP limit, lower one of them until it doesn't. For Microsoft 365 destinations, keep ingestion concurrency below the EWS/Graph throttling thresholds even though you're pushing via IMAP — the underlying mailbox is still subject to platform-wide limits.

Source and destination tool choices#

The market splits into three categories of IMAP migration tooling.

Native provider import wizards#

Gmail's "Check mail from other accounts (POP3)" and Microsoft 365's IMAP migration batch are free, supported by the destination vendor, and limited. Both work for straightforward, low-volume jobs. Both struggle with very large mailboxes, folder hierarchies more than two or three levels deep, and any source provider that wants OAuth instead of basic auth. They also offer essentially no observability — when something fails, you find out from the user.

Use these when you have a handful of mailboxes, no folder complexity, and time to babysit each one.

Hosted SaaS migration platforms#

Cloud-based tools that you authorize against both sides and then walk away from. They scale to thousands of mailboxes, handle throttling and retries automatically, and report progress through a dashboard. The trade-off: every credential and every message goes through the vendor's infrastructure. For some compliance regimes that's fine; for others (HIPAA in certain configurations, FedRAMP-adjacent work) it's a hard stop or at least a long DPA conversation.

Desktop migration tools#

Run locally on your workstation. They authorize against source and destination directly, hold credentials in your OS keychain, and move data without an intermediary cloud. Throughput is bounded by your uplink instead of a shared multi-tenant pool, which is actually faster for small to mid-sized projects than most people assume. Mailbox Taxi is one of these — built for IT admins and MSPs who would rather not add another SOC2 vendor to their data flow for a one-time migration.

How to choose#

Match the tool category to the project shape. Five mailboxes, internal team, low complexity: native wizard. Two thousand mailboxes, mixed sources, ongoing service: hosted SaaS that you've vetted. Anything in between, especially anything involving sensitive content or strict data residency rules, runs on the desktop. The pre-flight items in the email migration checklist work regardless of which category you pick.

Putting it together: a planning template#

The plan that survives contact with reality looks roughly like this:

Discovery week. Inventory every mailbox: size, folder count, attachment characteristics, last-login. Test IMAP connectivity from your migration host to source and destination. Confirm authentication method for each side. Identify the largest 10 mailboxes — they'll dominate the schedule.

Pilot week. Migrate 5–10 mailboxes across the size and complexity distribution. Time them. Watch for throttling. Verify folder structure, read state, and special folders (Sent, Drafts, Trash, Junk) after each pilot mailbox. Adjust concurrency based on what you observe.

Bulk window. Run the full migration in batches. For 400 mailboxes at 5 concurrent, expect 4–7 calendar days of bulk run time depending on average mailbox size. Schedule batches around source-provider quiet hours where you can.

Delta and cutover. Once the bulk pass is done, run a delta sync that picks up everything that arrived during the bulk window. Cut the MX records. Run one final delta to catch the last few hours. Total cutover window: typically 1–4 hours for a clean delta, depending on volume and DNS propagation.

Post-cutover. Monitor user reports for 7–14 days. The issues that show up tend to be missing rules, missing signatures, and folder names that didn't survive UTF-7 conversion. Have a playbook for each.

A note on hybrid scenarios#

You will sometimes see a setup where IMAP is "good enough" for mail but you need something more comprehensive for the surrounding data. The right pattern is usually a tool that does IMAP for mail and uses native APIs for calendar/contacts/rules — not pure IMAP for everything with a separate calendar tool that nobody remembers to run. Make sure the tool you pick names the protocol it uses for each data type, and make sure it has a strategy for the things IMAP doesn't carry.

Common pitfalls#

Two failure patterns account for most botched IMAP migrations.

The first is underestimating folder-name translation. IMAP folder names are encoded in UTF-7 historically, and modern providers handle this differently. A folder named "Résumés / 2023" might arrive at the destination as "R&AOk-sum&AOk-s _ 2023" if the conversion goes wrong. Pilot a mailbox with non-ASCII folder names early and confirm what the destination shows.

The second is assuming the destination has unlimited capacity. Microsoft 365 mailboxes have storage quotas (typically 50 GB or 100 GB depending on license). Gmail accounts vary by Workspace SKU. If a source mailbox is larger than the destination quota, the migration will fail partway through with Quota exceeded and the user will be locked out of receiving new mail until you free space. Check destination quotas during discovery, not during the bulk run.

When to stop trying to be clever#

If you find yourself writing custom Python to handle a provider's specific throttling pattern, ask whether the project really needs a custom solution or whether the off-the-shelf tool would handle it if you reduced concurrency by half. Most IMAP migration "complexity" is throughput optimization that doesn't matter once you accept the migration will take a week instead of a weekend.

The migrations that finish on time are the ones where the admin picked sane concurrency, validated authentication for both sides on day one, ran a real pilot, and kept the scope honest about what IMAP doesn't carry. The migrations that don't finish are the ones where someone assumed it would be like copying files.