Moving one mailbox to a new host is a form with six fields. A bulk migration of a hundred is a different problem, and the difference isn't arithmetic. It's that a hundred mailboxes contain a hundred opportunities for something to go wrong quietly — a wrong password, a source server that throttles after the fortieth connection, a folder that stops copying at 4,000 of 12,000 messages and reports success.
A bulk migration driven from a CSV solves the mechanical part: one file, one job, parallel workers, per-mailbox progress. What actually determines whether the bulk migration was any good is what happens after the progress bars finish, and that's where most tooling stops paying attention.
This covers the file format, the validation pass that catches bad rows before anything connects, how the run behaves, and the completeness audit that checks whether the mail actually arrived.
Before You Touch the Bulk Migration CSV
Two prerequisites, and skipping either wastes an evening.
The destination mailboxes must already exist. A bulk migration copies mail into mailboxes; it doesn't create them. If you're provisioning a hundred people, use bulk mailbox creation first — CSV upload with admin-set passwords, or bulk invites if you would rather each person set their own.
You don't need destination passwords. This surprises people who have used other tools. Authentication to your own mailboxes is handled internally, so the CSV contains source credentials only. If a migration tool asks for both sides, that's a tool that could be reading its own customers' mailboxes with credentials in a spreadsheet.
The Bulk Migration File Format
Three columns when every account is at the same provider, because the server details come from the provider you pick in the form:
source_email,source_password,destination_email
alice@oldhost.com,app-pw-1,alice@yourdomain.com
bob@oldhost.com,app-pw-2,bob@yourdomain.comSix columns when the sources are mixed — an acquisition where half the team is on Google Workspace and half is on a cPanel server:
source_email,source_password,destination_email,source_host,source_port,source_security
alice@gmail.com,app-pw-1,alice@yourdomain.com,imap.gmail.com,993,ssl
bob@outlook.com,app-pw-2,bob@yourdomain.com,outlook.office365.com,993,ssl
carol@oldhost.com,pw-3,carol@yourdomain.com,mail.oldhost.com,993,sslThe parser is deliberately forgiving, because these files are produced by hand and by export tools with opinions:
| Rule | Detail |
|---|---|
| File size | 2 MB maximum |
| Encoding | UTF-8; other encodings are rejected rather than silently mangled |
| Header row | Optional, detected automatically |
| Delimiter | Comma, tab, or semicolon — detected automatically |
| Blank lines | Skipped |
| Comments | Lines starting with # are skipped |
| Addresses | Lowercased and trimmed |
| Rows per batch | 100 on Starter, 300 on Pro, 1,000 on Agency |
Semicolon support isn't a nicety. Excel in most European locales exports semicolon-delimited CSV, and a parser that only accepts commas turns that into one column of nonsense.
One warning about spreadsheets: a password beginning with =, +, or - is interpreted as a formula and destroyed on save. Prepare these files in a text editor, or quote the column.
Source Passwords Are the Hard Part
Every mailbox in a bulk migration needs a working IMAP credential at the source, and at the large providers your normal password isn't one.
| Source | What the CSV needs |
|---|---|
| Gmail / Google Workspace | An app password, which requires 2-Step Verification on the account first |
| Microsoft 365 | An app password if the tenant allows them; otherwise an administrator has to enable IMAP and basic auth for the migration window |
| Yahoo, AOL, iCloud | App password |
| cPanel and traditional hosting | The normal mailbox password |
Collecting a hundred app passwords from a hundred people is the real cost of a bulk migration, and it's worth being honest with yourself about it before promising a date. Where you've administrative control at the source, generating credentials centrally is faster than asking. Where you don't, send instructions with screenshots and expect a long tail.
Delete the CSV when the bulk migration finishes. It's a file full of live credentials.
Validation Before Anything Connects
Paste or upload the data, click Preview & validate, and every row is categorised before a single connection is opened:
- Ready — valid and queued.
- Errors — malformed address, missing password, or a destination mailbox that doesn't exist. Skipped.
- Warnings — this destination was migrated recently, so you may be about to import duplicates.
- Duplicates — the same source-and-destination pair appears twice in the file.
- Over limit — beyond your plan's per-batch cap.
Fix the file and re-preview as many times as you like; nothing has happened yet. The check that saves the most time is "destination mailbox not found", because the usual cause is a typo in a domain name that would otherwise have produced a hundred confusing authentication failures instead of one obvious one.
Bulk Migration Options That Matter
Folder scope. All folders, standard folders only (Inbox, Sent, Drafts, Trash, Archive, Junk), or Inbox only. Standard-only is the right default for most migrations: it skips the labels, tags, and provider-specific virtual folders that produce duplicate copies of the same message.
Import since. A date floor. Two years of mail instead of eleven is a much shorter migration, and for most teams the older mail is archive material that can move later or not at all.
Skip duplicates. Leave this on. It's what makes a re-run safe — the second pass adds only what is missing rather than doubling everything, which matters because you'll re-run at least once.
Batch name. Label it. Three weeks later "Acme — phase 2" is considerably more useful than a timestamp.
What Happens During a Bulk Migration Run
Accounts are processed in parallel, bounded by plan: 2 concurrent on Starter, 5 on Pro, 10 on Agency. The cap isn't arbitrary. Source providers rate-limit aggressively, and forty simultaneous IMAP connections from one address to one provider is indistinguishable from an attack — the reliable outcome is temporary blocking, which turns a slow migration into a failed one.
Each account moves through Queued, Starting, Validating, Planning, Importing with a percentage, and then Completed, Failed, or Cancelled. You can close the page; the work continues server-side.
Three controls while it runs:
- Cancel all stops running and queued accounts. Completed ones keep their mail.
- Retry failed re-queues only the failures, and you can correct a source password first — which covers the single most common failure by a wide margin.
- Resume restarts a batch that paused itself.
That last one has a specific trigger: if account storage reaches 90%, the bulk migration pauses and emails you. Filling a destination mid-run produces half-copied mailboxes and no clear record of where each one stopped, so stopping early is the better failure. Free space or upgrade, then resume.
You also get mail when the batch completes, and a separate alert if more than half the accounts fail — that pattern usually means one systemic cause, such as the source provider blocking the connection, rather than fifty individual problems.
The Part After the Progress Bar
Here is the failure mode that matters, and it's the reason to care about which tool you use.
IMAP copying is a long sequence of individual operations. A source server that drops a connection, throttles mid-folder, or returns a truncated listing can leave a folder short — and the copier, having processed everything it was told about, reports success. The progress bar reaches 100%. Nothing is wrong on screen. Four thousand messages are missing.
So the run is audited independently. Five minutes after a large bulk migration completes, a reconciliation pass compares the set of unique Message-IDs at the source with the set at the destination, folder by folder. Message-ID is the right key here because it's assigned by the original sender and survives copying, so it identifies the same message on both sides regardless of internal identifiers.
When mail is missing, three things happen automatically:
- A report of what is short, and where, is stored against the migration.
- Folders that came up short are marked partial rather than complete — which is what makes a resume actually re-fetch them, since a resume skips anything marked complete.
- You get an email saying so, in plain language: which folders, how many messages, and what to do next.
The audit only examines folders that were in the bulk migration plan, so deliberately excluded ones — Gmail's All Mail, which is a virtual folder containing copies of everything else — don't raise false alarms.
An email telling you a bulk migration was incomplete isn't a good look. It's a great deal better than the alternative, which is finding out in November when someone needs an invoice from March.
Cutover Sequence
The migration is the easy half. The order of operations around it's what determines whether anyone loses mail.
- Create the destination mailboxes and confirm they accept logins.
- Run the first bulk migration pass while MX still points at the old host. Nothing is live yet, so a failure costs nothing but time.
- Verify. Check the audit report and open a few mailboxes by hand — folder counts, oldest message, newest message.
- Cut MX over, having lowered the TTL a day or two earlier so propagation is quick.
- Run a second pass with skip-duplicates on, to sweep up everything that arrived at the old host during propagation. This step isn't optional; DNS propagation isn't instant and mail keeps arriving at the old server for hours.
- Keep the old mailboxes for a month. Don't cancel the old hosting the same week. Storage is cheap; a re-run isn't possible once the source is gone.
Frequently Asked Questions
How many mailboxes can one bulk migration cover?
100 per batch on Starter, 300 on Pro, 1,000 on Agency. Within a batch, 2 to 10 run concurrently depending on plan — that cap exists to avoid being rate-limited by the source provider.
Do I need the destination passwords?
No. The CSV holds source credentials only; authentication to your own mailboxes is handled internally.
Can I run it again without duplicating everything?
Yes, with skip-duplicates enabled — the second pass adds only what is missing. This is what makes the post-cutover sweep safe.
What happens if a source password is wrong?
That account fails and the rest continue. Fix the password on the failed row and use Retry failed, which re-queues only the failures.
Will it move my folders and read status?
Folder structure and message flags such as read and starred are preserved. Provider-specific constructs — Gmail labels, which aren't really folders — map imperfectly by nature; standard-folders-only avoids most of that.
How do I know a bulk migration lost nothing?
A large bulk migration is reconciled automatically by comparing unique Message-IDs on both sides, and short folders are marked partial and reported by email. You can also verify by hand: compare folder counts and check the oldest and newest message in each.
Can I do this over the API?
Yes. Migrations can be started, monitored, cancelled, and retried through the REST API or an AI agent over MCP. See API migrations.
How long does a bulk migration take?
The bounded resource is almost always the source provider's throttling, not our side. A rough planning figure for typical business mailboxes is a few hours for a small team and overnight for a large one — which is why the first pass should happen before cutover, when the duration doesn't matter.
