Migrate Inbox Messages to Outlook Live

Topic Last Modified: 2009-09-09

If you want a quick and simple way to convert all your existing on-premises mailboxes, including Microsoft Exchange Server 2007 or Exchange Server 2003 mailboxes, to Outlook Live mailboxes, you can do it by using POP subscriptions to migrate e-mail messages from the Inbox of these mailboxes to Outlook Live.

Overview of the migration process

If you manage an on-premises messaging system, you can create a service account that has access to all mailboxes. You use the service account to access the mailboxes on behalf of the users, without knowing their individual credentials in the on-premises messaging system. You then use Windows PowerShell V2 to create POP subscriptions on behalf of the users in Outlook Live using the credentials of the service account in the on-premises messaging system.

For example, suppose you want to convert all your existing on-premises mailboxes to Outlook Live mailboxes. You can create POP subscriptions to import users' Inbox messages from the on-premises messaging system to the mailboxes in Outlook Live. After the conversion from the on-premises messaging system to Outlook Live is complete, you remove the POP subscriptions from the Outlook Live mailboxes.

Note   When you access a mailbox using POP, you can only download e-mail messages from the Inbox. Other mailbox items, such as calendar entries, contacts, and tasks aren't supported by POP. Also, POP can't download folders or their contents, except for the contents of the Inbox.

Before you begin

This procedure assumes that you're already enrolled in Outlook Live, and that you've already created Outlook Live mailboxes for all your users.

To create POP subscriptions on behalf of the users in your Outlook Live organization, you have to use a script in Windows PowerShell. To learn how to install and configure Windows PowerShell and connect to Outlook Live, see Use Windows PowerShell.

Import users' Inbox messages from on-premises mailboxes

Follow these steps.

1. Configure your on-premises messaging system to allow POP access to user mailboxes

If your on-premises messaging system is Microsoft Exchange, POP access to mailboxes isn't enabled by default. To enable POP access to mailboxes in an Exchange organization, see the following topics:

2. Configure the service account that has access to all mailboxes

To create a service account that can access all mailboxes in an Exchange organization, see the following topics:

3. Create a CSV file that maps the on-premises mailboxes to the Outlook Live mailboxes

To add POP subscriptions to many accounts at one time, you have to correlate the existing mailboxes in the on-premises messaging system and the existing mailboxes in Outlook Live by using a CSV file. The CSV file is in the following format:

RemoteAlias,OutlookLiveAlias
User1,NewUser1
User2,NewUser2
User3,NewUser3

Note   Don't modify the variable names in the first row. They're used in the Windows PowerShell code in the next step.

The RemoteAlias value is the alias on the left side of the @ symbol for the user's e-mail address in the on-premises messaging system. For example, if the e-mail address is akohl@contoso.edu, the value of RemoteAlias is akohl. The OutlookLiveAlias value is the alias on the left side of the @ symbol for the user's e-mail address in Outlook Live. The values of RemoteAlias and OutlookLiveAlias for a user may be the same.

If you have an existing on-premises directory service, you can use a directory export tool to export the account data from your existing directory service to a CSV file. For information about how to use the Csvde tool in Windows Server 2003 to export data from the Active Directory directory service or from the Active Directory Application Mode (ADAM) directory service, see CSVDE.

To export the account data from Outlook Live, you can run the following command after you have connected to the Outlook Live server-side runspace:

Get-Mailbox | Format-List Name,PrimarySmtpAddress,Alias -Wrap > <file path>\OutlookLive.txt
4. Create the Windows PowerShell script

On a local computer that has Windows PowerShell installed and configured, perform the following steps:

  1. Copy the following code snippet.
    #Begin custom variables
    $filePath = "C:\My Documents\StudentList.csv"
    $outlookLiveAliasOrg = "live.contoso.edu"
    $remoteOrg = "corp.contoso.edu"
    $serviceAccount = "corp\serviceaccount"
    $password = 'Pa$$word1'
    $popIncomingServer = "pop.corp.contoso.edu"
    $popIncomingAuth = "Basic"
    $popIncomingPort = "995"
    $popIncomingSecurity = "SSL"
    $popLeaveOnserver = $false
    #End custom variables
    
    $securePassword = (ConvertTo-SecureString -String $password -AsPlainText -Force)
    $students = Import-Csv $filePath
    
    if ($students -ne $null)
    {
    foreach($student in $students)
    {
    $subscriptionName = $student.RemoteAlias.Trim() + " Edu Subscription"
    $emailAddress = $student.RemoteAlias.Trim() + "@" + $remoteOrg
    $mailbox = $student.OutlookLiveAlias.Trim() + "@" + $outlookLiveAliasOrg
    $IncomingUserName = $serviceAccount + "\" + $student.RemoteAlias
    
    write-output ([string]::Concat("Creating Subscription: ", $subscriptionName," ", $emailAddress, " ", $mailbox))
    New-PopSubscription -Name $subscriptionName -IncomingUserName $IncomingUserName -IncomingPassword $securePassword -IncomingServer $popIncomingServer -EmailAddress $emailAddress -Mailbox $mailbox -IncomingAuth $popIncomingAuth -IncomingPort $popIncomingPort -IncomingSecurity $popIncomingSecurity -LeaveOnServer $popLeaveOnserver
    }
    }
  2. Paste the copied code snippet in Notepad or another text editor.
  3. Save the text file with a descriptive name and the .ps1 file extension, for example, POPMigration.ps1.
5. Customize the POPMigration.ps1 script

You have to customize the variables in the script to match the values required for your organization. The variables are described in the following table.

Note   Be sure to leave the existing quotation marks when you replace the example values with the correct values for your organization.

Variable Description

$filePath

This variable specifies the complete path and file name of the CSV file, for example, "C:\My Documents\StudentList.csv".

$outlookLiveAliasOrg

This variable specifies the Outlook Live domain, for example, "live.contoso.edu".

$remoteOrg

This variable specifies the on-premises domain, for example, "corp.contoso.edu".

$serviceAccount

This variable specifies the service account in the on-premises messaging system that has access to all the mailboxes using the format "domain\username", for example, "corp\serviceaccount"

$password

This variable specifies the password of the service account, for example, 'Pa$$word1'.

$popIncomingServer

This variable specifies the Internet-accessible name of the on-premises POP3 server, for example, "pop.contoso.edu".

$popIncomingAuth

This variable specifies the authentication method used by POP3 clients to connect to the on-premises POP3 server. Valid values are "Basic" and "SPA".

Note   The default value for Exchange 2007 and Exchange 2003 is "Basic".

$popIncomingPort

This variable specifies the TCP port number used by POP3 clients to connect to the on-premises POP3 server. Typical values are "110" for unencrypted connections and "995" for encrypted connections.

Note   The default value for Exchange 2007 is "995". The default value for Exchange 2003 is "110".

$popIncomingSecurity

This variable specifies the encryption method used by POP3 clients to connect to the on-premises POP3 server. Valid values are "None", "SSL", or "TLS".

Note   The default value for Exchange 2007 is "SSL". The default value for Exchange 2003 is "None".

$popLeaveOnserver

This variable controls the behavior of mail that has been imported from the on-premises mailbox to the Outlook Live mailbox. Valid values are $true or $false. When this variable is set to $false, mail that is imported to the Outlook Live mailbox is removed from the on-premises mailbox. When this variable is set to $true, no mail is removed from the on-premises mailbox.

6. Run the script

After you customize the script, connect to the Outlook Live server-side runspace and run the script:

<script file name and path>

For example, if you saved the script named "C:\My Documents\POPMigration.ps1", run the following command:

"C:\My Documents\POPMigration.ps1"
Next steps

After you've performed these steps, check with your users to verify that messages were imported to their Outlook Live mailboxes. You may also want to remove the POP subscriptions after you have imported the users' e-mail messages.

Ask users to confirm that messages were imported to their Outlook Live mailboxes

Users can log in to their on-premises mailboxes to verify that e-mail messages in their Inboxes were successfully imported. If you set the $popLeaveOnServer variable to $false, their on-premises Inbox should be empty.

A user can also check the status of the POP subscriptions in their Outlook Live mail by clicking Options > Account > Other Accounts. If you created the POP subscription using the script in this topic, the account name is "<user alias> Edu Subscription".

For more information, see FAQs: Downloading E-Mail from Connected Accounts.

Remove the POP subscriptions from the Outlook Live mailboxes

As long as a POP subscription exists, Outlook Live will poll the on-premises mailbox at regular intervals to retrieve new e-mail messages. The polling interval may be anywhere between 15 minutes and one hour.

If you are going to remove the migrated mailboxes from the on-premises messaging system, you should remove the POP subscriptions from the corresponding Outlook Live mailboxes. Removing the POP subscription doesn't remove any e-mail messages from the Outlook Live mailbox.

Ask Outlook Live users to remove the POP subscription themselves

Use Windows PowerShell to remove the POP subscription on behalf of the user

To remove an individual POP subscription from an Outlook Live mailbox

Run the following command after you have connected to the Outlook Live server-side session:

Remove-Subscription <subscription name> -Mailbox domain\alias

For example, if you created the POP subscription using the script in this topic, the POP subscription name is "<user alias> Edu Subscription". For the user akohl in the Outlook Live domain live.contoso.edu, run the following command:

Remove-Subscription "akohl Edu Subscription" -Mailbox live.contoso.edu\akohl
To remove all the POP subscriptions that you created

You can use the same CSV file that you used to create the POP subscriptions. Remember that the CSV file has the following format:

RemoteAlias,OutlookLiveAlias
User1,NewUser1
User2,NewUser2
User3,NewUser3

Note   Don't modify the variable names in the first row. They're used in the Windows PowerShell code in the next step. However, the RemoteAlias variable name and values aren't required to remove the POP subscriptions.

To create a Windows PowerShell script to remove all the POP subscriptions that you created, perform the following steps:

  1. Copy the following code snippet.
    #Begin custom variables
    $filePath = "C:\My Documents\StudentList.csv"
    $outlookLiveAliasOrg = "live.contoso.edu"
    #End custom variables
    
    $students = Import-Csv $filePath
    
    if ($students -ne $null)
    {
    foreach($student in $students)
    {
    $subscriptionName = $student.RemoteAlias.Trim() + " Edu Subscription"
    $mailbox = $student.OutlookLiveAlias.Trim() + "@" + $outlookLiveAliasOrg
    
    write-output ([string]::Concat("Removing Subscription: ", $subscriptionName," ", $mailbox))
    Remove-Subscription -Identity $subscriptionName -Mailbox $mailbox -Confirm:$false
    }
    }
  2. Paste the copied code snippet in Notepad or another text editor.
  3. Save the text file with a descriptive name and the .ps1 file extension, for example, RemovePOPMigration.ps1.
  4. Customize the following variables in the script:
    • $filePath   This is the complete path and file name of the CSV file, for example, "C:\My Documents\StudentList.csv".
    • $outlookLiveAliasOrg   This is your Outlook Live domain, for example, "live.contoso.edu".
      Note   Be sure to enclose the values in double quotation marks.
  5. Run the script after you have connected to the Outlook Live server-side runspace:
    <script file name and path>
    For example, if you saved the script named "C:\My Documents\RemovePOPMigration.ps1", run the following command:
    "C:\My Documents\RemovePOPMigration.ps1"
Read more

Outlook Live mailbox users themselves can use the Web management interface to set up Outlook Live to download e-mail from their other mailboxes. For more information, see Download E-Mail from Connected Accounts.

Page view tracker