How to Use the Email Migration Tool

The OpenSRS migration tool downloads mail from remote servers into existing OpenSRS mailbox accounts. It preserves subfolders, keeps original message dates, and skips messages that already exist in the destination account. This article shows you how to run a migration job in the Reseller Control Panel and in the Mail Administration Console (MAC), and how to review logs and common errors.

About the migration tool

Company and domain admins can use the migration tool to move user mail over IMAP4, IMAP4S, POP3, or POP3S. For POP3 accounts, only the Inbox is migrated — subfolders are not. The tool is available from the Bulk Tools area of the Control Panel and from the Tools menu of the MAC.

Before you begin

• Review and complete the broader migration preparation in Migrate to the OpenSRS Email Service.
• Ensure the target user accounts already exist in OpenSRS. The tool only downloads mail into existing mailboxes.
• Migrate no more than 500 mailboxes at a time. Split larger jobs into multiple batches.
• Gather source server hostname, the protocol you'll use, ports, and a username/password list.
• If you have a mix of POP3 and IMAP users, plan to run POP3 users in one Auto job and IMAP users in another IMAP4 job for better performance.

Step 1: Migrate mail through the Reseller Control Panel

1. In the Email section of the Control Panel, click the Email Domains tab.
2. Click the domain you want to migrate, then click the Bulk Tools tab.
3. Under Operation Type, select Migrate Users.
4. Complete the fields:
   • Job Name — a unique name. If blank, a numeric name is generated.
   • Server Hostname — the source server's hostname or IP.
   • Server Protocol — the retrieval protocol. Auto migrates the Inbox over POP3 and other folders over IMAP4. Use Auto for POP users.
   • Server Ports — ports for the chosen protocol. Set to 0 to disable a protocol. Click the plus sign to add more.
   • Folders to Skip — folders to ignore (optional, does not apply to POP3).
   • Translate Folder Name — source and destination folder names when they differ.
   • List of users and passwords — format: source_username,source_password[,local_username]. Use a non-comma delimiter if usernames contain commas.
5. Click Submit.

Step 2: Migrate mail through the MAC

1. Log in to the Mail Administration Console (MAC).
2. In the navigation pane, under Tools, click Migrate.
3. Select the New migration tab.
4. Complete the fields:
   • Job name — a unique name. If blank, a numeric name is generated.
   • Protocol — retrieval protocol. Auto migrates the Inbox over POP3 and other folders over IMAP4. Choose Auto if you have POP users.
   • Server — hostname or IP of the source server.
   • Ports — ports to connect on. For Auto, the ports are POP3, POP3s, IMAP4, and IMAP4s. Set to 0 to disable a protocol.
   • Skip — folders to ignore, one per line. Does not apply to POP3.
   • Translate — source and destination folder name pairs (source,destination), one pair per line. Use a colon as a delimiter if folder names contain commas.
   • Users — list of source and destination users and passwords, format: username,password[,local_username]. If local_username is omitted, the source username is used.
5. Click Migrate.

Step 3: Download migration logs

1. Log in to the MAC and click Migrate under Tools.
2. Click the Results tab, then click the email address for the job you want logs for.
3. At the bottom of the prompt, click Download log.

The downloaded text file shows whether each mailbox migrated successfully, failed, or partially migrated by folder.

Common migration error messages

Next steps

• Plan the full migration — the tool is one step in a broader process. See Migrate to the OpenSRS Email Service.
• Bulk create destination accounts — provision matching mailboxes before running a migration. See Bulk Tools.
• Update DNS post-migration — point MX records at OpenSRS once mail has moved. See Configure DNS for OpenSRS Hosted Email.
• Watch for service interruptions during migration — see Email Migration Service Interruptions.

Questions? Contact OpenSRS Support.