How to Use the Automated Email Migration Tool to Transfer Mail from cPanel/Gmail

Moving your email history to a new mailbox can feel daunting — nobody wants to lose years of correspondence. StackCP includes a built-in Email Migration tool that copies your existing mail (from an IMAP source, Gmail, or Outlook) into your new StackCP mailbox automatically, without any downtime and without touching your DNS settings.

Important: Set Up Your Destination Mailbox First

Before starting a migration, you need to have already created the destination mailbox in StackCP (see our companion Email Accounts guide). Critically, set the destination mailbox's password to match the password of the source mailbox you're migrating from. This is a specific requirement of how the migration tool authenticates and syncs — mismatched passwords will cause the migration to fail.

Step 1: Open the Email Migration Tool

1. Log in to StackCP.
2. Go to Manage Hosting, then Options / Manage on your package.
3. Select Email Migration.

Step 2: Enter Your Source Mailbox Details

1. Enter the Hostname of your source mail server. If you're not sure, a common guess is mail.yourdomain.com, though this can vary depending on your previous host.
2. Enter the Username and Password of the source mailbox — remembering that this password must match what you set for the destination mailbox in StackCP.
3. Select Sync to begin the migration.

Step 3: Understand What the Migration Actually Does

• It copies your existing emails into the new StackCP mailbox — it does not delete or move anything from the source. Your original mailbox remains untouched and unaffected.
• You can run the migration multiple times for the same mailbox if needed — subsequent runs only pull across new emails since the last sync, without creating duplicates.
• Migration happens one mailbox at a time per hosting package.
• There's no downtime involved, and the process doesn't touch your domain's DNS settings — meaning your live, current mail flow isn't interrupted while the migration runs in the background.

Step 4: Migrating Specifically From Gmail

If your source mailbox is a Gmail account, there's an extra step, since Gmail requires an app-specific password rather than your regular account password for this kind of connection:

1. Ensure 2-Step Verification is enabled on the Google Account you're migrating from (a prerequisite for generating an app password).
2. In your Google Account, go to Security > App Passwords.
3. Select Mail as the app, and Other (Custom name) as the device — name it something identifiable, like "StackCP Migration."
4. Generate the app password, and use this (not your normal Gmail password) as the password in the migration tool.

Step 5: Wait for the Migration to Complete

Migration time depends on the size of the source mailbox — a small mailbox may complete quickly, while a large mailbox with years of history can take longer. You can check back periodically rather than needing to keep the page open continuously.

Step 6: Update Your DNS Only After Confirming the Migration Worked

Since the migration tool doesn't touch DNS automatically, it's your responsibility to update your domain's MX records (see our companion DNS records guide) to point to StackCP once you've confirmed the migration completed successfully and all your expected mail has arrived. Don't switch your DNS before verifying the migration, since doing so prematurely could mean new incoming mail arrives at the new mailbox before the historical migration has actually finished pulling in your older messages, creating a confusing, split mail history.

Step 7: Import Your Contacts Separately (If Needed)

The Email Migration tool moves email messages — it doesn't automatically bring across your contacts/address book. To migrate contacts:

1. Export your contacts from your previous provider as a CSV or vCard file (check your previous provider's own export instructions).
2. In Stackmail webmail, go to the Contacts tab.
3. Select Import, and choose your exported file.

Common Mistakes Beginners Make

• Setting a different password on the destination mailbox than the source. This is the single most common cause of a failed migration — the passwords must match.
• Switching DNS before confirming the migration is complete. Wait until you've verified all expected mail has arrived before updating MX records.
• Using a regular Gmail password instead of an app password when migrating from Gmail, which will fail due to Google's security requirements for this kind of connection.
• Forgetting to migrate contacts separately, since the tool only handles email messages, not your address book.

Troubleshooting

"My migration failed immediately." Double-check that the destination mailbox's password exactly matches the source mailbox's password (or app password, for Gmail).

"I'm not sure what hostname to use for my source mailbox." Try mail.yourdomain.com as a common default; if that doesn't work, check with your previous hosting provider for their specific IMAP server address.

"The migration seems to have stalled or is taking a long time." Large mailboxes with years of history naturally take longer — check back periodically rather than assuming failure, unless a clear error message appears.

"I ran the migration once, then made a mistake and want to run it again." This is safe — re-running the migration only pulls across new mail since the last successful sync, without creating duplicate copies of what's already been migrated.

A Practical Migration Timeline

For a business planning an email migration without wanting to disrupt day-to-day operations, a sensible sequence looks like:

1. Create the destination mailbox in StackCP, setting its password to match the source mailbox exactly.
2. Start the migration and let it run — since it doesn't affect your live mail flow, you can continue using your existing mailbox normally while this happens in the background.
3. Once complete, spot-check the new mailbox — confirm recent emails, older archived folders, and attachments all came across as expected.
4. Run the migration a second time shortly before switching DNS, to catch any mail that arrived in the source mailbox during the gap since your first sync — remember, repeat runs are safe and won't duplicate anything already migrated.
5. Update your MX records to point to StackCP once you're confident everything has transferred correctly.
6. Keep the old mailbox accessible for a short period after switching, as a safety net, in case you need to double-check anything that might not have transferred as expected.

Why the Non-Destructive Design Matters

It's worth appreciating why StackCP's migration tool is built to copy rather than move mail: it means there's essentially no risk of data loss during the process. If something goes wrong, is interrupted, or simply doesn't look right once complete, your original mailbox remains completely untouched and you can simply try again, rather than facing a situation where email has already been deleted from the source before you've confirmed it landed safely at the destination.