Mailbox migration

Move users and mail from Office 365, Zoho Mail, Gmail or any IMAP/POP3 provider without losing history.

Updated November 15, 2026 5 min read Maintained by Altgence

#What migration covers

Alt8Mail imports users and mail from an existing provider into a tenant. The customer-admin mailbox import is gated by the migration license feature. It copies source messages into Alt8Mail; it does not delete the source mailbox unless the source itself is changed after cutover.

Migration is not a replacement for DNS cutover planning. The target domain must already be created and verified, and the target users must exist or be created during mapping.

#Supported sources

Source	Protocol in current code	Important detail
Generic IMAP	`imap`	Recommended path for standards-compliant providers
POP3	`pop3`	Imports the INBOX only; no folder mapping
Gmail / Google Workspace	Gmail API OAuth	A source-mailbox token or refreshable token bundle is required; generic IMAP also works
Microsoft 365 / Outlook / Exchange Online	Microsoft Graph OAuth	Generic IMAP via `outlook.office365.com` also works
Zoho Mail	Generic IMAP	There is no dedicated Zoho migration API path
Google Workspace domain-wide delegation	Not supported	Use source-mailbox credentials or generic IMAP
PST, EWS or on-prem Exchange	Not supported	No PST/EWS importer is present
Zoho CRM	Not a mailbox importer	CRM is an add-on/integration, separate from mailbox migration

Do not promise PST migration, Exchange Web Services migration or a Zoho-specific API import.

#Before you start

Confirm the migration entitlement is active.
Create and verify the target domain in Customer Admin.
Create target users, or prepare to create them during mapping.
Confirm the source provider allows the chosen protocol and the account can authenticate.
For Gmail or Microsoft Graph, prepare OAuth credentials and consent for the source mailbox. Generic IMAP remains a fallback.
Ensure the target user quotas and storage capacity can hold the imported mail, attachments and versions.
Take a configuration backup and record the current DNS TTL before cutover.

Never send source mailbox passwords through email or support tickets. The import screen seals credentials server-side; keep the uploaded job file on a trusted administrative workstation and remove it when the job is complete.

#The import workflow

Open Customer Admin → Users → Import mailboxes.
Choose the protocol, host, port and security. IMAP commonly uses 993 with TLS; POP3 commonly uses 995 with TLS. Port 25 is blocked for connected-account and import egress.
Choose whether to include Junk/Spam, Trash/Deleted and Drafts. Junk and Trash are off by default; Drafts are on by default. Confirm this is what your retention and user expectations require.
Set the maximum message size. The default is 50 MB, with a hard maximum of 64 MB.
Upload a CSV/TSV/XLSX or enter rows manually. Columns are email, password (or an OAuth token/JSON bundle), and optional notify_email.
Validate the source logins. Entries that fail authentication are marked and skipped; they do not block the rest of the job.
Map each source mailbox to an existing user or create a new user. Auto-match by email where possible.
Start the job. It runs server-side and is resumable; a closed browser tab does not cancel it.
Watch per-item progress and the event log. Cancelling stops after the current batch; already copied mail remains.
Download the results CSV, which contains generated credentials where users were created.
Download the fidelity report for message, folder, attachment, unread, starred and calendar counts.
Spot-check the target mailbox in webmail before cutover.

The current job limit is 500 mailboxes per job. The job-creation body is limited to 8 MB. Larger migrations should be split into controlled batches.

#Copy behavior and fidelity

The source mailbox is not deleted by Alt8Mail.
Messages, folder placement, read/unread state, flags, sent dates and attachments are preserved where the source protocol exposes them.
POP3 imports only the INBOX and cannot provide folder fidelity.
ClamAV scans imported messages when configured. Infected messages are routed to quarantine; scanner failures fail the item closed with a retryable cursor.
Messages above the scan cap can be imported unscanned and are logged.
The fidelity report is the evidence to use before cutover. Do not rely only on a total message count.

#Cutover plan

Use a staged cutover rather than changing MX immediately.

Pilot. Import a small group, verify folder fidelity and send/receive behavior.
Bulk import. Run the remaining batches and resolve authentication or quota failures.
Freeze writes. Ask users to stop sending from the old provider during the final delta if the source cannot be resynced easily.
Final sync. Import new messages or rerun the batch only after understanding whether the job is idempotent for your source. Do not duplicate mail by guessing.
MX cutover. Lower DNS TTL ahead of time, then make the MX/autodiscover/web changes with a rollback record.
Verify inbound. Confirm new mail arrives to Alt8Mail for every target domain.
Verify outbound. Confirm SPF, DKIM, DMARC and PTR are correct before inviting users to send.
Retire the source only after acceptance. Keep the source read-only for a defined grace period if the contract allows it.

Old messages remain in Alt8Mail after cutover; the source can be retired once fidelity and retention obligations are satisfied.

#Troubleshooting the import

Symptom	Check
`auth_failed`	Use the full mailbox address, confirm the password or token, and verify the provider allows IMAP/POP3 or the required OAuth scopes.
Job stalls	Check the Control mail logs, target database health and source rate limits. A resumable job can be retried; do not launch duplicate jobs against the same mailbox.
Missing folders	POP3 cannot preserve folders. For IMAP, confirm the folders exist and are not excluded by the job options.
Missing recent mail	Run a final delta or reconcile from the source before MX cutover.
Attachment mismatches	Compare the fidelity report with the provider's own export. Very large or provider-specific items may be excluded by source policy.
Target quota errors	Increase the user/domain quota or split the import.
Mail is quarantined	Review the target quarantine queue; do not disable scanning to make an import appear complete.

#Platform-level imports

System Control has separate import tools for platform operators: IMAP, mbox files/directories and Maildir. These write into an active local mailbox and are not the tenant self-service workflow. They run one at a time, stage under /var/vmail/.control-imports, and log progress and errors. Use the customer-admin migration workflow when a tenant is moving from another provider.

Operate for storage, backups and mail flow.
Secure for domain authentication and DMARC.
Troubleshooting for general mail-delivery checks.

Need a hand?

We can help with the next step.

Talk to the team