Bulk Migrate cPanel Mailboxes via CSV

If you're consolidating an entire agency, hosting a multi-tenant setup, or just moving more than 5-10 mailboxes from cPanel, the bulk migration tool saves hours over single-account imports. Upload a CSV of accounts, we validate, you confirm, and we queue every migration in parallel. This guide covers building the CSV correctly, the folder-strategy options, and how to monitor a running batch.

Before you start

• The bulk migration tool is on Starter, Pro, and Agency plans. Nano accounts don't have it.
• You need every destination mailbox already created on TrekMail before launching the batch. The destination addresses in your CSV must match existing TrekMail mailboxes — we won't auto-provision them as part of migration. Use Bulk Mailbox Creation first if you have many to make.
• Have all source passwords ready. Bulk migration can't reset source passwords; you'll need them current. If passwords are random/forgotten, reset them on the source provider first.
• Same IMAP server for every account is the easy case. Different servers (multi-host migrations) work too, but the CSV format changes.

Step 1 — Find the source IMAP details

In cPanel:

1. Log in to one source cPanel account.
2. Email Accounts → Connect Devices on any single account.
3. Note the Secure SSL/TLS Settings values:

If all accounts are on the same shared host, the IMAP server is the same for every account — that's the same-host case. If accounts span multiple cPanel servers (e.g., one client per cPanel install), you need per-row server overrides — see Step 2.

Step 2 — Build the CSV

Two formats are supported. Pick based on whether all your source mailboxes share the same IMAP host.

Format A — All accounts on the same IMAP host (3 columns)

The simplest case. Three columns: source email, source password, destination email.

source_email,source_password,destination_email
alice@oldhost.com,cpanel-pw-1,alice@yourdomain.com
bob@oldhost.com,cpanel-pw-2,bob@yourdomain.com
info@oldhost.com,cpanel-pw-3,info@yourdomain.com

You'll provide the server details (source_host, source_port, source_security) on the bulk-import form itself, applied to every row.

Format B — Accounts on multiple IMAP hosts (6 columns)

When your batch spans multiple cPanel installations or different providers:

source_email,source_password,destination_email,source_host,source_port,source_security
alice@site1.com,pw1,alice@yourdomain.com,mail.site1.com,993,ssl
bob@site2.com,pw2,bob@yourdomain.com,mail.site2.com,993,ssl
charlie@hostB.com,pw3,charlie@yourdomain.com,imap.hostingB.net,993,ssl

When you use Format B, toggle Per-row server overrides on the bulk-import form. The server fields on the form are then ignored — each row uses its own.

CSV mechanics that matter

• Header row is required — don't skip it.
• Order of columns is fixed. Don't reorder.
• No commas inside any field unless the field is wrapped in double quotes. Passwords with commas should be quoted: "my,password".
• No trailing whitespace in any field. Some spreadsheet exports add invisible trailing spaces; trim them before saving.
• Encoding: UTF-8. Most editors do this by default; Excel sometimes saves as Windows-1252 which can break special characters in non-ASCII names.
• Empty rows in the file are ignored — fine to leave blank lines between groups.
• Maximum file size is bounded by your plan's batch limits (Starter typical: 100 rows; Pro: 500; Agency: thousands). The form rejects oversize files with an error.

You can download a working template from the Import → Bulk Import → Download template link.

Step 3 — Run the bulk import

1. In TrekMail, open Import → Bulk Import tab.
2. Provider — pick Other / Generic IMAP for cPanel.
3. Server details — if you're using the 3-column format, fill in the host, port, and security here. For the 6-column format, check Per-row server overrides and these fields don't apply.
4. Folder strategy — three choices:
   • All folders — copies every folder visible to the source IMAP (Inbox, Sent, Drafts, Spam, Trash, custom labels). Bigger but complete.
   • Standard folders only — Inbox, Sent, Drafts. Skips Spam, Trash, and custom labels. Faster, cleaner for archival migrations.
   • Inbox only — just the Inbox. Smallest copy. Good when you've already moved everything except for catching last-minute mail.
5. Import since (optional) — date filter. "Only emails received after this date." Useful for skipping ancient mail.
6. Skip duplicates — checked by default. If a Message-ID is already present on the destination, don't copy it again. Useful when re-running a batch where some rows succeeded previously.
7. Batch name — optional human-friendly label so you can identify this batch later.
8. Upload CSV or Paste CSV into the text area.
9. Click Preview & Validate.

Step 4 — Review the preview

The preview shows three groups:

• Valid rows — pass all checks. Source email format valid, destination mailbox exists on your account, password not empty.
• Invalid rows — fail validation. Each error is shown inline: "Destination mailbox not found", "Source email malformed", "Empty password", etc.
• Skipped rows — duplicates within the CSV itself (same source-destination pair listed twice), or already-active migrations (same destination already being migrated in another batch).

Fix invalid rows by editing the CSV outside TrekMail, then re-paste/upload. The preview is non-destructive — nothing's queued yet.

When the preview looks right, click Start Migration. Toast: "Bulk migration started — N accounts queued."

If you re-submit the exact same CSV again accidentally, the system detects it (idempotency) and shows: "This batch was already submitted. Showing existing results." — no duplicate queuing, you're redirected to the existing batch.

Step 5 — Monitor and recover

The bulk batch detail page shows:

• Overall progress — total rows, completed, failed, in progress.
• Per-row status — same states as single-mailbox migrations: queued, running, paused, completed, failed, partial.
• Failure reasons for failed rows — usually source authentication or connectivity issues.

Actions you can take on a running batch:

• Cancel — stops queued jobs from starting; running jobs finish their current message then stop.
• Retry failed — re-queues only the failed rows after you've fixed whatever was wrong (e.g., updated source passwords).
• Continue on partial rows — picks up where the previous run left off, doesn't restart from scratch.
• Update password on individual rows — if a single row's password was wrong, edit just that one and retry without re-uploading the whole CSV.
• Resume the whole batch from a paused state.
• Delete — removes the batch record after completion (doesn't delete imported mail).

You can also Export report — downloads a CSV with each row's final status and any error message. Useful for handing off to whoever needs proof of completion.

Common bulk-mode problems

"Destination mailbox not found"

You listed alice@yourdomain.com as destination but that mailbox doesn't exist on TrekMail yet. Create it first (Mailboxes page or Bulk Mailbox Creation), then re-run.

"Authentication failed" on many rows

If it's just a few rows, the passwords for those source accounts are wrong. Fix the CSV and use Retry failed.

If it's most rows: probably you're using the wrong username format. Some hosts want just alice not alice@yourdomain.com. The bulk form doesn't expose a username-format switch directly — open a support ticket if you suspect this and we'll advise on how to set it up.

"Source rate-limit exceeded"

Some hosting providers limit concurrent IMAP connections per source host. If we try to pull 50 mailboxes at once from one server and the server only allows 10 concurrent IMAP sessions, the surplus rows fail with rate-limit errors. Solution: contact the source host to temporarily lift the limit, or process the batch in smaller chunks.

"Some imports completed but counts don't match what's on cPanel"

Same explanations as the single-mailbox guide — check folder strategy (you may have chosen "Standard folders only" and excluded custom labels), date filter, and skip-duplicates setting.

Tips for very large batches

• For 100+ accounts, plan to migrate over the weekend or during a low-traffic period. Server load on both sides is significant.
• Pre-warm the destination by creating mailboxes a day in advance so they're indexed before mail starts arriving.
• For multi-day migrations, keep the old MX records pointing at the source host until 24h after the bulk completes — that way you don't lose new inbound mail during the import.
• Cut DNS over (point MX at TrekMail) after the bulk's first pass. Then run a second "delta" bulk import in 24-48 hours to catch anything that arrived at the old server in between. Skip duplicates does the right thing on the second pass.