You can use Windows PowerShell and a CSV file to migrate the contents of user mailboxes from an on-premises IMAP messaging system to Outlook Live. Here's how:
To prepare for the e-mail migration:
Return to top
Here are the required attributes for each user:
The migration request will fail if any one of these attributes isn't included in the header row of the CSV migration file. Also, type the attributes exactly as they are shown. Attributes can't contain spaces. They must be a single word. For example, Email Address is invalid. You must use EmailAddress.
Here's an example of the format for a CSV migration file. In this example, three users are migrated:
EmailAddress,UserName,Password terrya@contoso.edu,terry.adams,1091990 annb@contoso.edu,ann.beebe,2111991 chrisc@contoso.edu,chris.cannon,3281986
The first row, or header row, of the CSV file lists the names of the attributes, or fields, specified in the rows that follow. Each attribute name is separated by a comma.
Each row under the header row represents one user and supplies the information that will be used to migrate that user. The attribute values in each row must be in the same order as the attribute names in the header row. Each attribute value is separated by a comma.
Use any text editor, or an application like Microsoft Office Excel, to create the CSV file. Save the file as a .csv or .txt file.
Use the username and password of the super-user account in the UserName and Password fields for each row of the CSV migration file. For example, in the IMAP implementation for Microsoft Exchange, use the format Domain/Admin_UserName/User_UserName for the super-user credentials. For IMAP servers that support Simple Authentication and Security Layer (SASL), use the format Admin_UserName*User_UserName where the asterisk ( * ) is a configurable separator character. For more information about how to use super-user credentials, see the documentation for your IMAP server.
Note When you submit a new migration request, the CSV file is uploaded to the Microsoft datacenter over a Secure Sockets Layer (SSL) connection. The information from the CSV file is encrypted and stored on the Microsoft Exchange servers at the Microsoft datacenter.
Let's say you're migrating e-mail from Microsoft Exchange for Terry Adams, Ann Beebe, and Chris Cannon. You have an administrative service account, where the username is administrator and the password is Pa$$word1. Here's what your CSV file would look like:
terrya@contoso.edu,contoso-students/administrator/terry.adams,Pa$$word1 annb@contoso.edu,contoso-students/administrator/ann.beebe,Pa$$word1 chrisc@contoso.edu,contoso-students/administrator/chris.cannon,Pa$$word1
Alternatively, let's say you're migrating those users' e-mail from a Dovecot server, with an administrative service account (administrator and Pa$$word1). Here's what your CSV file would look like:
EmailAddress,UserName,Password terrya@contoso.edu,administrator*terry.adams,Pa$$word1 annb@contoso.edu,administrator*ann.beebe,Pa$$word1 chrisc@contoso.edu,administrator*chris.cannon,Pa$$word1
It's a best practice to run a test migration of a small batch of users before you migrate a large number of users. In the test migration, you can do the following:
Perform the following steps to migrate mailboxes to Outlook Live:
The first step in the migration process is to test the availability of your IMAP server and to verify the server's FQDN and the port used to receive the IMAP requests. Run the following Windows PowerShell command to test IMAP server availability:
Test-MigrationServerAvailability -RemoteServer <server FQDN> -Port <port number>
Here's an example for an IMAP server named imap.contoso.edu using port 143, which is the port reserved for unencrypted IMAP communication:
Test-MigrationServerAvailability -RemoteServer imap.contoso.edu -Port 143
The results of the command confirm whether you successfully connected to the IMAP server.
The next step is to use the New-MigrationBatch cmdlet to submit a new migration batch request. If a migration batch is already running, you can't submit a new one until the current batch is finished running. Use the Get-MigrationBatch cmdlet to determine if a migration batch is running.
The following syntax includes the required parameters:
New-MigrationBatch -Imap -Name <name for the migration batch> -CSVData ([System.IO.File]::ReadAllBytes(<path of the CSV migration file>)) -MaxConcurrentMigrations <number between 1 and 10> -RemoteServer <server FQDN> -Port <port number> Timezone <timezone>
Here's an example:
New-MigrationBatch -Imap -Name MigrationBatch1 -CSVData:([System.IO.File]::ReadAllBytes("C:\Users\Administrator\Desktop\MigrationBatch_1.csv")) -MaxConcurrentMigrations 3 -RemoteServer imap.contoso.edu -Port 143 -Timezone "Pacific Standard Time" -ExcludeFolders "Deleted Items","Junk Mail"
Here's a description of the parameters used in this example.
Imap
None. No value is required.
The Imap parameter specifies IMAP as the migration type. In this release, IMAP is the only option. Future releases may include other messaging solutions, such as POP or Windows Live Hotmail.
Name
MigrationBatch1
The Name parameter provides a name for the migration batch request.
CSVData
C:\Users\Administrator\Desktop\MigrationBatch_1.csv
The CSVData parameter provides the absolute path for the CSV migration file. The CSV file is located on the computer on which the administrator is running Windows PowerShell.
MaxConcurrentMigrations
3
The MaxConcurrentMigrations parameter specifies the number of connections to the IMAP server. Three connections means that three mailboxes will be migrated at any one time until all the rows in the CSV file are processed.
RemoteServer
imap.contoso.edu
The RemoteServer parameter specifies the FQDN of the IMAP server for the on-premises messaging system.
Port
143
The Port parameter specifies the port on the server used to receive the IMAP requests.
TimeZone
"Pacific Standard Time"
The TimeZone parameter specifies the time zone of the administrator who is submitting the migration batch. You can use Windows PowerShell to retrieve time zone names from the registry, for example:
Get-ChildItem "HKLM:\Software\Microsoft\Windows NT\CurrentVersion\Time zones" | FL pschildname
ExcludeFolders (Optional)
"Deleted Items","Junk Mail"
The ExcludedFolder parameter specifies the folders that you don't want to migrate to Outlook Live. Folder names are relative to the IMAP root on the on-premises mail server.
If the CSV file is validated and the availability of the IMAP server is verified, a migration job is created for the new migration batch.
Run the following command to start the migration batch:
Start-MigrationBatch
Here's an example to start a migration and have the migration status e-mail message sent to multiple recipients:
Start-MigrationBatch -NotificationEmails "super-user@contoso.edu","helpdesk@contoso.edu","CIO@contoso.edu"
By default, the migration status e-mail message is sent to the administrator who runs the Start-MigrationBatch cmdlet, but you can include additional recipients by using the optional NotificationEmails parameter.
The message sent after the migration batch is finished running contains the following information:
In the MigrationErrors.csv file attached to the migration status e-mail message, use the information in the ErrorMessage column of each row to identify and fix the problem that caused the row to fail. Then resubmit the fixed rows in a new CSV file.
Repeat steps 2 and 3 to submit and start additional migration batches. Each migration batch has its own CSV migration file. The Name parameter for each migration batch must be unique. Only one migration batch can be active at any one time.
After you submit and complete all migration batches, the next step is to configure your MX record to route e-mail sent to your organization to Outlook Live. For step-by-step instructions, see Use an MX Record to Direct Mail to Your Domain.
Until you change your MX record, e-mail sent to users is still routed to their on-premises mailboxes. When a user mailbox is successfully synchronized, the on-premises mailbox and Outlook Live mailbox are periodically synchronized until you complete the overall migration. This lets users use their Outlook Live account to access e-mail sent to their on-premises mailbox. After you configure your organization's MX record, mail is sent directly to Outlook Live.
Important It can take from 24 to 72 hours for the updated MX record to be propagated. Wait at least 24 hours after you change the MX record before you complete the migration. Be sure to verify that mail is being routed to Outlook Live mailboxes before you complete the migration.
The final step in the migration process is to run the Complete-Migration cmdlet to finalize the migration process. When you complete the migration, Microsoft Exchange performs a final synchronization for all migration requests.
Run the following command to complete the migration batch:
Complete-Migration
Here's an example that completes a migration and has the final migration status message sent to super-user@contoso.edu.
Complete-Migration -NotificationEmails super-user@contoso.edu
By default, the final status message is sent to the administrator who runs the Complete-Migration cmdlet.
You can get status on migration batches in progress or pending, and on the overall migration before it's completed.
Run this command to get status on the migration batch that's currently in progress or is pending:
Get-MigrationBatch
This command returns the following information:
Run this command to get status on the overall migration:
Get-MigrationStatus
This command returns the following information for the overall migration, which can consist of one or more migration batches:
Run this command to stop a migration batch that is being processed:
Stop-MigrationBatch
You can only stop migration batches that have mailboxes that are in the process of being migrated or are waiting to be migrated. Stopping a migration won't affect mailboxes that have been migrated. If all migration requests in a migration batch are either complete or failed, this command won't run. The migration of mailboxes that are being actively migrated is completed before the migration batch is cancelled.
The administrator receives a migration status e-mail message that specifies how many mailboxes successfully completed migration before the batch was stopped. The e-mail also has an attached migration errors CSV file that includes the rows that were in progress when the migration was stopped and the rows waiting to be migrated.
You can get help for the IMAP migration cmdlets at the Windows PowerShell command line. Use command-line help to identify the parameters that are used with each cmdlet and the appropriate syntax.
Command-line help can return different detail levels of information. Use the following commands to get more targeted help at the command line.
Get-Help <cmdlet>
Provides information about the cmdlet usage and syntax.
Get-Help New-MigrationBatch
Get-Help <cmdlet> -Examples
Shows examples of common cmdlet usage.
Get-Help New-MigrationBatch -Examples
Get-Help <cmdlet> -Detailed
Provides the cmdlet description, syntax, a full list of parameters and their usage, and examples.
Get-Help New-MigrationBatch -Detailed
Learn more about the Get-Help cmdlet and associated syntax in the Microsoft Exchange Server help: Getting Help. Although this topic refers to Exchange Server 2007 for on-premises deployments, the content also applies to Outlook Live and Windows PowerShell V2 with WinRM.