Mailbox migration guide
Move business mailboxes with an inventory, validation, and rollback plan.
A mailbox migration is more than copying files. The source format, destination mailbox, folder mapping, permissions, indexing, DNS cutover, and user access all need separate checks.
Build a source and destination inventory
Record the mailbox list, approximate message count and size, important folders, aliases, forwarders, filters, shared access, retention needs, and active email clients. Confirm which items the source provider can export and which settings must be recreated manually.
Create and activate each destination mailbox before importing historical content. The destination local part must match the exported mailbox when a Maildir archive contains a mailbox-named folder.
1,200 + 800 + 500 = 2,500 expected messages across three mailbox exportsCompare the source total, import result, and indexed destination total. A count difference is an investigation signal, not automatic proof of data loss.
- Confirm the authoritative DNS provider and current MX records.
- Record mailbox storage and message counts without copying message content.
- Map old Inbox, Sent, Drafts, Junk, Trash, Archive, and custom folders.
- Identify provider-specific labels, rules, calendars, contacts, or metadata that the export may not preserve.
Prepare the destination without cutting over MX
Verify domain ownership, create the destination mailboxes, assign access, and confirm the receiving service is active. Keep existing MX records in place while destination setup and historical import are being tested.
Prepare new client settings and secure mailbox credentials separately from API or SMTP relay credentials. Test access through EmailDesk webmail or a controlled compatible client before the cutover.
Import Maildir data into the matching mailbox
For cPanel or another Maildir-based source, preview the ZIP and its folder mapping before import. Use browser upload only for a small test archive; the documented server-staged or protected HTTPS flow is more appropriate for large archives.
The EmailDesk migration flow writes valid message files into the destination Maildir and indexes them for the built-in mailbox. Imported historical folder placement is preserved, while unsafe or system-only archive files are skipped.
- Root cur and new folders map to Inbox.
- Known Sent, Drafts, Junk, Trash, and Archive folders keep their role.
- Unknown folders remain custom folders instead of being guessed.
- A successful staged import removes its staged ZIP; a failed import keeps it for reviewed retry.
Cut over DNS and validate both mailbox views
After import validation, publish the intended MX records at the authoritative DNS provider and allow for TTL-based propagation. During the overlap, check both old and new providers because different senders can see different cached MX answers.
Confirm new inbound delivery, outbound sender authentication, webmail access, client access, folder placement, recent and older messages, and the built-in EmailDesk index. Roundcube reads physical Maildir through IMAP; the built-in mailbox depends on the EmailDesk database index.
- Roundcube missing mail can indicate Maildir ownership or access problems.
- Roundcube-visible mail missing from EmailDesk can indicate indexing is incomplete.
- Keep a small source-versus-destination count and spot-check log without copying message bodies.
- Retain the old service and export until the agreed validation window is complete.
Keep migration limits and rollback clear
A source export may omit provider-specific labels, rules, shared permissions, contacts, calendars, or unsupported metadata. Message counts can also differ because of duplicates, corrupt files, skipped system files, or folder mapping. EmailDesk cannot recreate data that the source provider did not export.
DNS propagation is not instantaneous and recipient systems remain outside EmailDesk control. If validation fails, pause the cutover, keep or restore the documented prior MX values where appropriate, and resolve mailbox mapping, permissions, or indexing before retiring the source.
Frequently asked questions
Questions about this guide.
Does importing historical mail consume outbound sending quota?
No. Mailbox import is not an outbound provider handoff. Imported data can affect storage usage, but it does not create recipient or attachment sending units.
Why can mail appear in webmail but not in the built-in EmailDesk mailbox?
Webmail reads physical Maildir through IMAP, while the built-in mailbox reads the EmailDesk index. The files may exist before indexing has completed.
Will every source-provider setting migrate?
No. Available results depend on the source export. Provider-specific labels, rules, permissions, contacts, calendars, and unsupported metadata may need separate recreation.
Continue with evidence