Complete Email Migration Guide

1. Overview and Architecture

The safest migration is a staged process. First copy the existing mail, then verify it, then change mail routing, then configure authentication and finally perform a last synchronization.

2. Requirements and Preparation

• Root or suitable administrative access to the cPanel server.
• A mailbox already created on cPanel.
• Source mailbox credentials.
• Destination mailbox credentials.
• Access to the DNS provider controlling the domain's authoritative nameservers.
• Public IP address of the new cPanel mail server.
• Port 993 reachable from the server running imapsync.

Do not change MX records at the beginning

Keep the old mail provider active until migration, verification, final synchronization and DNS cutover are complete. This prevents messages from being lost during the transition.

Identify authoritative DNS

dig NS example.com +short

The returned nameservers tell you where the authoritative DNS zone is hosted. DNS records should be changed at that provider unless cPanel is authoritative for the domain.

3. Create the Destination Mailbox

In cPanel:

1. Open Email → Email Accounts.
2. Create the mailbox, for example user@example.com.
3. Set a strong mailbox password.
4. Confirm the mailbox exists.

To list mailboxes from the shell, where supported:

uapi --user=CPANEL_USERNAME Email list_pops

4. Create the Mail Hostname

Create an A record for the hostname used by cPanel mail clients:

Verify:

dig A mail.example.com +short

Expected result:

203.0.113.10

Verify that cPanel/Dovecot is listening for IMAPS:

ss -ltnp | grep ':993'

Port 993 should normally show Dovecot listening on IPv4 and/or IPv6.

5. Test IMAP Connectivity Before Migration

Test the source

imapsync \
  --host1 imap.titan.email \
  --port1 993 \
  --ssl1 \
  --user1 'user@example.com' \
  --justconnect

Test the destination

imapsync \
  --host1 mail.example.com \
  --port1 993 \
  --ssl1 \
  --user1 'user@example.com' \
  --justconnect

These tests establish network/TLS connectivity. A successful --justconnect test does not necessarily prove that the password is correct.

Authenticate and synchronize folders without messages

imapsync \
  --host1 imap.titan.email \
  --port1 993 \
  --ssl1 \
  --user1 'user@example.com' \
  --host2 mail.example.com \
  --port2 993 \
  --ssl2 \
  --user2 'user@example.com' \
  --justfolders

Enter the source and destination passwords only when prompted. A successful run should report successful authentication and no errors.

6. Migrate the Actual Mail

Once connectivity and authentication are confirmed, run the actual synchronization:

imapsync \
  --host1 imap.titan.email \
  --port1 993 \
  --ssl1 \
  --user1 'user@example.com' \
  --host2 mail.example.com \
  --port2 993 \
  --ssl2 \
  --user2 'user@example.com'

The command copies messages from host1 to host2. With this basic command, the source mailbox remains available.

What to expect

• Folders are discovered and synchronized.
• Messages are identified and copied.
• Attachments are part of the messages and are copied with them.
• Running the synchronization again is normally useful because imapsync can skip messages that are already present.
• A successful run should end with Detected 0 errors and a successful exit status.

7. Verify the Migrated Mailbox

• Open cPanel Webmail.
• Confirm Inbox messages.
• Confirm Sent messages.
• Confirm Drafts.
• Confirm custom folders.
• Open several messages.
• Open/download several attachments.
• Compare approximate message counts with the source.
• Confirm dates, senders and subjects look correct.

Do not delete the source mailbox yet.

8. Change MX Records

Only change MX after the mailbox has been migrated and verified.

Remove the old provider's MX records and add the new mail server. Example:

The exact priority is not the important part; the important part is that the intended mail server is the MX destination and obsolete MX records are not left active unintentionally.

Verify authoritative DNS directly

dig NS example.com +short
dig MX example.com @AUTHORITATIVE_NAMESERVER +short

Also check public resolvers:

dig MX example.com @1.1.1.1 +short
dig MX example.com @8.8.8.8 +short

9. DNS Propagation and Caching

Different DNS resolvers may temporarily return different MX records because they cache records according to their TTL. The authoritative nameservers are the best reference for determining whether the change was actually published.

Do not repeatedly edit MX records simply because one resolver still has the old value.

10. Configure SPF

SPF tells receiving servers which systems are authorized to send mail for your domain.

If the new mail server sends directly from 203.0.113.10, a simple SPF example is:

v=spf1 ip4:203.0.113.10 ~all

Critical SPF rule

A domain should normally have one SPF TXT policy. Do not create multiple independent SPF TXT records beginning with v=spf1.

If the old provider is no longer sending mail, remove its SPF include. If another legitimate service still sends mail (website, marketing platform, CRM, Microsoft 365, Google Workspace, etc.), its authorization must remain in the same SPF record.

Verify:

dig TXT example.com +short

11. Configure DKIM

DKIM adds a cryptographic signature to outgoing mail. cPanel/Exim can generate the DKIM key pair.

Find the cPanel-generated DKIM information

In cPanel, open:

Email → Email Deliverability → Manage for the domain.

cPanel will show a suggested DKIM record, normally using a selector such as:

default._domainkey

The DNS record generally looks like:

Host/Name:
default._domainkey

Type:
TXT

Value:
v=DKIM1; k=rsa; p=YOUR_PUBLIC_KEY

Useful server locations

cPanel commonly stores DKIM keys under:

/var/cpanel/domain_keys/private/
 /var/cpanel/domain_keys/public/

Do not paste the contents of a private-key file into DNS.

12. Configure DMARC

DMARC tells receiving systems how to handle mail that fails authentication/alignment and provides reporting capabilities.

A safe starting policy is monitoring mode:

After SPF/DKIM are confirmed and legitimate senders are known, the policy can be strengthened gradually, for example with quarantine and eventually reject.

13. Test Incoming and Outgoing Mail

Inbound test

From Gmail, Outlook or another external mailbox, send:

external-account@example.net
        ↓
user@example.com

Confirm the message arrives in cPanel Webmail.

Outbound test

From cPanel Webmail, send:

user@example.com
        ↓
external Gmail/Outlook address

Confirm delivery. Check both Inbox and Spam.

Authentication checks

For a delivered message, inspect the recipient's message headers. Look for results similar to:

SPF: PASS
DKIM: PASS
DMARC: PASS

A Gmail rejection such as:

550-5.7.26 Your email has been blocked because the sender is unauthenticated.
SPF = did not pass
DKIM = did not pass

usually means DNS authentication is missing, incorrect, not propagated, or the sending server is not authorized.

14. Perform the Final Synchronization

After MX is changed and mail is being delivered to the new server, perform one final source-to-destination sync if the old mailbox remained active during the transition.

imapsync \
  --host1 imap.titan.email \
  --port1 993 \
  --ssl1 \
  --user1 'user@example.com' \
  --host2 mail.example.com \
  --port2 993 \
  --ssl2 \
  --user2 'user@example.com'

This catches messages that arrived on the old server before DNS propagation completed.

15. Production Cutover

1. Migration completed.
2. Mailbox verified.
3. MX changed.
4. Inbound delivery verified.
5. SPF corrected.
6. DKIM published.
7. DMARC published.
8. Outbound delivery verified.
9. Final imapsync completed.
10. Keep the old provider available for a safety period.
11. Only after everything is stable should the old mail service be cancelled.

16. Troubleshooting

MX still shows the old provider

dig MX example.com +short
dig MX example.com @1.1.1.1 +short
dig MX example.com @8.8.8.8 +short
dig MX example.com @AUTHORITATIVE_NAMESERVER +short

If authoritative DNS is correct but a public resolver is old, wait for its cache to expire.

Inbound mail does not arrive

• Check MX.
• Check that mail.example.com resolves to the correct IP.
• Check port 25 and the mail server firewall.
• Check Exim status/logs.
• Confirm the mailbox exists.

Useful commands:

dig MX example.com +short
dig A mail.example.com +short
systemctl status exim
tail -f /var/log/exim_mainlog

Gmail says SPF failed

• Check the SPF TXT record.
• Ensure the sending IP is authorized.
• Ensure there is only one SPF policy.
• Remove obsolete provider mechanisms only when those services no longer send mail.

Gmail says DKIM failed

• Check the selector shown by cPanel.
• Check the TXT record name.
• Check that the complete public key was copied without accidental changes.
• Confirm DNS has propagated.
• Check the outgoing message headers for the DKIM-Signature selector.

imapsync authentication fails

• Verify the mailbox address.
• Verify the password privately at the prompt.
• Confirm IMAP is enabled on the source.
• Confirm port 993 and SSL/TLS settings.
• Check whether the provider requires an app password or special authentication method.

There is one extra message on the destination

This can happen when the destination mailbox already contained a welcome/system message before migration. Do not delete it automatically. Compare the message and decide whether it should remain.

17. Security Rules

• Never put mailbox passwords in screenshots, tickets, public documentation or shell history.
• Never publish DKIM private keys.
• Do not use destructive imapsync deletion options during a normal migration.
• Keep the old provider active until the migration is verified.
• Maintain backups where possible.
• Use strong mailbox passwords.
• Use TLS for IMAP and SMTP connections.
• Restrict server access and keep the operating system/cPanel updated.

18. Final Production Checklist

• Domain resolves correctly.
• Mail hostname A/AAAA records are correct.
• Destination mailbox exists.
• Source IMAP connectivity works.
• Destination IMAP connectivity works.
• Folder synchronization works.
• Messages migrated successfully.
• Attachments verified.
• MX points to the new mail server.
• Inbound external mail reaches cPanel.
• SPF authorizes the actual sending server.
• DKIM record exists and outgoing signatures pass.
• DMARC record exists.
• Outbound Gmail/Outlook delivery works.
• Final synchronization completed.
• Old provider has not been deleted prematurely.
• Contacts/calendars/signatures/filters/forwarders were recreated if required.
• Users have correct mail-client settings.

Typical cPanel mail-client settings

19. Quick Migration Flow

CREATE MAILBOX
      ↓
CREATE mail.domain.com A RECORD
      ↓
TEST IMAP CONNECTION
      ↓
TEST AUTHENTICATION
      ↓
SYNC FOLDERS
      ↓
MIGRATE EMAILS
      ↓
VERIFY MAIL + ATTACHMENTS
      ↓
CHANGE MX
      ↓
WAIT / CHECK DNS PROPAGATION
      ↓
TEST INBOUND
      ↓
CONFIGURE SPF
      ↓
CONFIGURE DKIM
      ↓
CONFIGURE DMARC
      ↓
TEST OUTBOUND
      ↓
FINAL IMAPSYNC
      ↓
KEEP OLD PROVIDER TEMPORARILY
      ↓
FINAL CUTOVER COMPLETE

Page View Counter

This documentation uses a server-side SQLite counter. Each successful page load increments the total view count.

The counter is stored on the server, so it is not reset when the browser is refreshed or closed.