Hotmail Mail Migration Toolkit Implementation Guide Legacy Mail Service, POP3, or IMAP4 into Hotmail Published: February 2009
Abstract
This document is intended for Microsoft partners (IT, operations, and development team) implementing and deploying the Windows Live @edu Mail Migration Toolkit. It describes the technical aspects of the Windows Live @edu Mail Migration Toolkit for implementing the Windows Live @edu Hotmail® migration solution.
Disclaimer
The information contained in this document relates to pre-release software products and services that may be substantially modified before its first commercial release. Accordingly, the information may not accurately describe or reflect the software product when first commercially released. THIS GUIDE IS PROVIDED FOR INFORMATIONAL PURPOSES ONLY, AND MICROSOFT CORP. MAKES NO WARRANTIES, EXPRESS OR IMPLIED, WITH RESPECT TO THIS GUIDE OR THE INFORMATION CONTAINED IN IT.
Microsoft Live @edu Hotmail MMT v1 Implementation Guide
Mail Migration Toolkit Overview
IntroductionThe Microsoft Live Hotmail Mail Migration Toolkit (MMT) allows you to migrate mail content from Inboxes that support POP3 or Internet Message Access Protocol (IMAP4) protocols into the Windows Live Hotmail® email system. The MMT consists of the following:
Documentation (provided herein) A Help file documenting the Toolkit SDK (including Hotmail interaction) Source code for the POP3/IMAP4 migration libraries and Windows PowerShell™ cmdlets Sample code that uses the MMT SDK
o Windows application for end-user migration of a single mailboxo Web application for end-user migration of a single mailboxo Sample Windows PowerShell™ scripting code for bulk migrationo Sample Windows PowerShell™ scripting code for contact migration
Note The MMT does not support migrating mail into Outlook Live mail.
Any questions or feedback should be sent to: the Windows Live Commercial Partner Center using this e-form: https://support.live.com/default.aspx?productkey=wlpc&mkt=en-ww
PrerequisitesThis chapter assumes that the reader is an IT professional who understands e-mail protocols, has a basic understanding of Windows PowerShell™ scripting, and has a basic understanding of Web page design and Web hosting.
Terms and Acronyms Used in This DocumentTerm Description
DNS Domain Name Service - an Internet service that holds information about a domain, including IP addresses for mail and web servers.
ILM Microsoft Identity Lifecycle Manager. Formerly named Microsoft Identity Integration Server. Used to automate directory service data replication and transformation; e.g. creating WLID accounts based on Active Directory entries.
IMAP4 Internet Message Access Protocol 4 – email protocol to allow a local client to access email on a remote server.
Microsoft Live @edu Hotmail MMT v1 Implementation Guide
Term Description
Microsoft Partner Support
Partner support team that provides assistance for Microsoft go-to-market partners, such as Microsoft Live@edu. File Support Tickets via the Windows Live Commercial Partner Center using this e-form: https://support.live.com/default.aspx?productkey=wlpc&mkt=en-ww
MMT Mail Migration Toolkit
Partner Consumer of the toolkit for the purpose of mail migration
POP3 Post Office Protocol 3 - email protocol to allow a local client to access email on a remote server.
Windows PowerShell™ Microsoft Windows powerful scripting and command line environment.
WL Mail Windows Live Mail client – powerful desktop client for consolidation of email accounts.
WLAC Windows Live Admin Center – service used to register a domain and create user accounts on the Windows Live platform.
WLAC SDK Admin Center Software Development Kit used to script user account creation and management.
WLID Windows Live ID. A username and password used to authenticate with Windows Live services. Synonymous with a “Passport ID”.
About the MMTThe MMT is a client application written in Microsoft C# with a Windows PowerShell™ interface. See the MMT architecture diagram below (figure 1). The program consists of a number of dynamic-link libraries (DLLs) that use the Windows PowerShell command platform for input and execution.
At a very high level, the MMT does the following:
1. Reads in a list of source e-mail accounts and destination Hotmail® accounts2. Processes each account and
a. Creates a destination Hotmail accountb. Logs into each source e-mail account and retrieves the mail folders and content in each
e-mail messagec. Copies mail folder names and mail content into Hotmaild. Copies contact information into the Windows Live Contact storee. Logs the success or failure of each account migration
Microsoft Live @edu Hotmail MMT v1 Implementation Guide
Your existing e-mail folders, mail content and contact information will not be modified by the MMT, so using this toolkit will have no effect on your current e-mail accounts. The migrated mail will have the following properties:
1. Same header information as source2. Same date and time stamp3. Same content and attachments4. Same sender info5. No anti-virus or spam filtering during migration
Samples are included in the toolkit to demonstrate the migration of a single mailbox and a number of mailboxes.
ResourcesThe school will need the following resources to implement mail migration:
IT Staff Development Staff
Feature ListThis version of the Mail Migration Toolkit supports the following:
1. Extraction of mail folders and mail content from POP3 and IMAP4 e-mail source2. Injection of mail folders and mail content into Windows Live Hotmail®
a. Windows Live Mail does not support sub-folders. IMAP Subfolders will be flatten to the same level as the parent folder.
3. Migration of mail settings a. Signature – users signatureb. Options – Miscellaneous settings like SaveSentMail, VacationResponse, MailForwarding
etcc. Lists – Used for spam control and security. E.g.: white list, block list of addresses, domainsd. Filters – Rules for organizing incoming mail into different folders
NOTE: Migrating mail settings requires custom coding by the school to pull these settings out of your POP/IMAP4 provider and link them to the Hotmail Injector inputs. The MMT contains sample code that demonstrates how to do this.
4. Migration of contacts
Note Migration of Calendar information is not supported in this version.
Microsoft Live @edu Hotmail MMT v1 Implementation Guide
The MMT:
1. Runs as a client with a Windows PowerShell™ interface2. Runs only on the Windows platform3. Comes with sample code for single-user and bulk migration4. Contains Windows PowerShell cmdlets and the object model for third parties to write migration
scripts
Language SupportDocumentation and support are available in English only.
Migration ScenariosTwo basic migration scenarios are supported by MMT:
1. User-initiated migration, where the end user inputs the name and password for their existing mailbox, which data and folders they want to move, and the destination mailbox (this could be pre-determined by the partner for the user). The concept is that the partner will host Web pages on their intranet to collect this information from the end user, then call the MMT which runs in their data center.
2. Bulk migration, where the administrator has the credentials of both the source and destination e-mail accounts. In this scenario, the administrator would import a list of account names containing source account name and password, as well as Hotmail® account name. After the platform validates that this is a valid administrator of this domain (via a call to Admin Center API to verify the LiveID or Certificate) the domain is assigned a short-lived-ticket (SLT) so the administrator has rights to move content to a Hotmail mailbox in their domain. The admin has the option to create the Hotmail accounts on the fly during the migration if they do not exist already.
Sample ScenariosTwo sample scenarios are presented below. These scenarios are simple in design, and require e-mail downtime and/or mail client reconfiguration. For more complex scenarios, where downtime is not permitted or e-mail client settings cannot be changed, it is recommended that the partner contract with a system integrator that is experienced with e-mail migrations.
Scenario 1: School Offers Self-Initiated Migration to StudentsContoso University wants to offer Hotmail® to students, who have their own e-mail provider (for example, AOL, Yahoo, Gmail) today. Contoso University uses the MMT to give them a way to self-service a mail migration.
Linda, you had a red line above Sample Scenarios, so I wasn’t sure what you meant by the red line?
Microsoft Live @edu Hotmail MMT v1 Implementation Guide
The following is assumed:
1. Domain name is contosouniversity.com2. End user has existing e-mail with third party provider (for example, AOL, Yahoo, Gmail) that
supports POP3 or IMAP43. School provisions a new Windows Live Account for student in school domain.4. Migration is done by student, self-initiated5. The MX record for the contosouniversity.com domain is pointing to Hotmail 6. Current e-mail client is unknown7. Hotmail client will be Web-based or Windows Live Mail.
Contoso provisioning:
Assumptions: School is already enrolled in the Microsoft Live@edu program and has contosouniversity.com domain MX record changed to Hotmail (see Hotmail Step by Step Onboarding Guide)
1. Contoso University creates student Hotmail account .2. School notifies student of new Windows Live@edu email account and password3. Contoso University creates a Web page where student can migrate their content using the MMT.
Student provisioning:
1. Student signs onto Contoso University portal that migrates their 3rd party email to Hotmail. The end user is redirected to Contoso University’s intranet migration page which uses the MMT Web User Initiated mail migration sample code.
2. Student enters their 3rd party email and Hotmail credentials3. Email is migrated
Scenario 2: Internal E-mail System, Bulk Migration of All MailboxesContoso University has an internal or third party e-mail system and wants to move 10,000 accounts to Hotmail® instead of waiting for the students to migrate the accounts themselves. Contoso wants to migrate mail content as well as student contact information.
The following is assumed:
1. Domain name is contosouniversity.com2. Client access to the existing mail system will be shut down during migration3. Existing mail system supports POP3, or IMAP4 and multiple folders4. The MX record will be pointing to the original e-mail system during the migration, and pointed to
Hotmail immediately following migration5. All Hotmail accounts are new and will be created in bulk6. Current client is Web-based7. Hotmail client will be Web-based
Linda, not sure if I interpreted your edits correctly?
Microsoft Live @edu Hotmail MMT v1 Implementation Guide
Contoso University provisioning:
1. Contoso University sends e-mail to students notifying them of outage over the weekend (this assumes migration can be completed in a 48 hour period).
2. On migration day, Contoso University shuts down client email access to existing email system. Although the students cannot access their email, incoming email will continue to arrive in old email boxes as long as the MX record points there.
3. Contoso University registers the domain contosouniversity.com with Windows Live Admin Center (WLAC) ( http://domains.live.com)
Contoso University chooses “No e-mail for domain” option, enters WLID credentials for administrator account, and changes DNS CNAME record to the value provided by WLAC to validate.o Contoso University contacts the Windows Live Commercial Partner Center using this
e-form: https://support.live.com/default.aspx?productkey=wlpc&mkt=en-ww Contoso University changes domain to “Windows Live Hotmail” in WLAC with no MX
change needed.4. Contoso University uses ILM or WLAC SDK to create all user Hotmail Inboxes, using accounts and
random passwords. All accounts are set to change password on first logon. 5. End user now has two e-mail accounts, existing and Hotmail6. Constoso University migrates mail content for existing accounts 7. Runs MMT for all accounts using POP3 or IMAP4 protocol ( includes all folders)8. When all migrations are complete, Contoso University changes MX record to Hotmail9. Contoso migrates user contacts from legacy system to Windows Live10. Contoso decommissions old e-mail system
Student provisioning:
1. Student signs into the Contoso University portal and is taken to first login experience page where they are asked to change their password and enter other personal information required by Hotmail.
2. End user is now routed to Hotmail. They see their old e-mail content and contacts have been migrated to Hotmail.
3. Subsequent logons, end user clicks on “check e-mail” and goes to Hotmail Web pages.4. For help or information on changing your MX record, please see the DNS Troubleshooting Guide.
Microsoft Live @edu Hotmail MMT v1 Implementation Guide
Extractors
The extractor is the part of the tool that will retrieve all the mail data from the source e-mail system. There are several ways in which the tool can communicate with this system. The two out-of-the-box extracting methods that the tool supports are by communicating through POP3 or IMAP4 protocols. If the source e-mail system does not support either protocol, or added functionality is required, the partner can create their own custom extractor.
Microsoft has provided the source code for the extractors to help partners modify or build their own. When reviewing the source code, you will see that the base class is InternetMailClient. InternetMailClient class is the parent of Pop3Client and Imap4Client. In order to build your own extractor, you must also build a class that is a parent of InternetMailClient. Your new class must query your e-mail platform for the messages.
Migration Data Objects
The extractor inserts all the data into data objects specific for the migration, like a folder or a mail message. Any custom extractor that the school builds has to populate objects within the data model schema.
Hotmail® Injector and Hotmail API
Once all the data objects have been populated they will be passed on to the injector and passed through to Hotmail. Source code is not included for the Hotmail injector to protect against misuse.
Migration Manager
This is the central traffic controller that calls the extractor and injector, and manages the connections between Hotmail and the school’s e-mail platform. The Migration Manager also keep track of all the synchronization keys and other states. This code is customizable and is part of the samples that Microsoft provides.
Interface
The tool supports different interfacing methods:
Microsoft provides a Windows PowerShell™ interface sample that can be used for scripting Bulk Migrations (both e-mail and contacts migration).
Microsoft also provides a sample Web page for entering source and destination information. The web sample does not use Windows PowerShell and directly interacts with the MMT SDK. Although it is a simple Web page, it shows how a User Initiated Migration can work. Schools can build any functionality that they require on top of the samples provided or use them as guidance to create something new.
Microsoft Live @edu Hotmail MMT v1 Implementation Guide
Contact Manager
The tool includes sample code to migrate contact information to the Windows Live Contact store. The sample code defines the available fields that are supported by the contact migration engine. Contact migration is accomplished by defining the fields to migrate (they must be a subset of the fields supported) in an xml file, and populating the fields of the xml file with contact information for each user account. Authentication is the same as mail migration authentication.
We support the migration of 23 contact fields in this verison of the MMT:
Microsoft Live @edu Hotmail MMT v1 Implementation Guide
</Business>
</Contact>
How to Install and Use the MMT
Installing the MMT
PrerequisitesThe following software components are required to run the MMT:
Microsoft .NET Framework 2.0 or greater if you are using Windows® XP SP2 Operating System (OS), Windows Server® 2003 Operating System, or Windows Server® 2008 (x32) Operating System. Windows Vista® has .NET 3.0 installed with the OS. Visit the Microsoft Download Center to download the Microsoft .NET Framework http://www.microsoft.com/downloads/results.aspx?pocId=&freetext=.net%20framework%202.0&DisplayLang=en#
Microsoft Windows PowerShell™ 1.0 or greater. Visit the Windows Server Web site to download Windows PowerShell http://www.microsoft.com/windowsserver2003/technologies/management/powershell/download.mspx
Minimum system requirementsOperating Systems Supported
Windows XP SP2 Windows Vista RTM Windows Server 2003 Windows Server 2008 (32 bit only)
Obtaining the MMTMMT is available on the Microsoft Connect site (http://connect.microsoft.com). You will need your Live@edu connect site credentials to login and download MMT. The download is a zipped Windows
Microsoft Live @edu Hotmail MMT v1 Implementation Guide
installer package that contains the WLMailMigration.msi. Using WinZip, unzip the file and copy this msi to your Windows machine and run the installer. You will be asked where you want to install the files; the default is:
C:\Program Files\Windows Live Mail Migration Toolkit\
Four sub-directories are created in the install:
Bin – contains the binaries used in mail migration Help – contains the Mail Migration object and class descriptions Samples – contains the sample code for three common scenarios, in three separate sub-
directories:
1. Windows application for end-user migration of a single mailbox (GuiUserInitiatedMigration)2. Web application for end-user migration of a single mailbox (WebUserInitiatedMigration)3. Sample Windows PowerShell™ scripting code for bulk migration (BulkMigration)4. Sample Windows PowerShell™ scripting code for contacts migration (ContactsMigration)
Source – Source code for POP3 and IMAP4 extraction and Windows PowerShell cmdlets
Running the MMTThe MMT is based on Windows PowerShell™ cmdlets (the native binary commands in Windows PowerShell) for each operation (getting source e-mail content and folders, creating Windows Live accounts, and copying e-mail content to Windows Live Hotmail®).
Get-POP3Mailbox – Retrieves the content from a POP3 mailbox (POP supports Inbox only) Get-IMAP4Mailbox – Retrieves mail folders and content from each folder from an IMAP4
mailbox New-HotmailMailbox –Add a Windows Live account with Hotmail Add-HotmailMailItem – Add mail folders and content from each folder to a Hotmail mailbox
These Windows PowerShell™ commands can be
Run from the Windows PowerShell command line Scripted to run multiple Windows PowerShell commands in a .ps1 file Executed from an application via Windows PowerShell pipeline calls
Sample CodeThe Mail Migration Toolkit contains four sets of sample code, described briefly here. All four samples contain a Readme.txt file in the root of the subdirectory to describe how to implement the code in your environment.
1. Sample Windows application for end-user migration of a single mailbox
Microsoft Live @edu Hotmail MMT v1 Implementation Guide
Subdirectory = GuiUserInitiatedMigration This sample was used to create a Windows client application. You can run the compiled version (Windows.Live.MailMigration.PowerShell.Gui.exe) located in the Bin directory. The sample application presents the end user with an interface to enter credentials (mail host, username and password) for the source mailbox and for the Hotmail® inbox. This sample assumes that the end user has an existing Hotmail inbox and knows their username and password for both mailboxes. If you want to modify the code, there are instructions in the readme.txt file located in the subdirectory.
2. Sample web page application for end-user migration of a single mailbox Subdirectory = WebUserInitiatedMigration
This sample is for creating web pages where end users can enter their email credentials for their POP3/IMAP4 mailbox, as well as their Hotmail mailbox. The sample consists of ASP.NET code that can be hosted on a web server. There are two web pages, one that collects credentials (mail host, username and password) for the source mailbox, and one that collects credentials for the Hotmail inbox. This sample assumes that the end user has an existing Hotmail inbox and knows their username and password for both mailboxes. Please refer to readme.txt for more details.
3. Sample Windows PowerShell™ scripting code for bulk migrationSubdirectory = BulkMigration
If you want to migrate a large number of mailboxes in bulk, this sample will outline the PowerShell calls needed to drive the migration. The sample demonstrates the migration of mailbox folders and content, as well as mailbox settings. An xml file is required that contains all of the information needed for the migration. Please refer to the readme.txt file located in the subdirectory for more details.
4. Sample Windows PowerShell™ scripting code for contact migrationSubdirectory = ContactMigration
If you want to migrate contact information for your accounts, to populate the contact list across all Windows Live services, such as Hotmail and Messenger, this sample will provide a template. Each account requires an xml file containing the list of contacts to migrate. The sample xml file in the Accounts folder contains the contact fields that are available for migration. You can migrate all of the fields or a subset. Please refer to the sample ps1 and xml files for more details.
Migration RateE-mail migration rate depends on a number of factors:
1. Rate of transfer from source2. Rate of transfer to destination
Microsoft Live @edu Hotmail MMT v1 Implementation Guide
3. Number of MMT instances running4. Number of e-mail messages5. Size of attachments6. Network bandwidth7. Class of client machine
In internal testing, Microsoft has benchmarked a single instance of the tool migrating up to 10 megabytes/minute. This translates to 14 gigabytes/day. By running multiple instances of the MMT in parallel, you can scale your migration linearly. Microsoft has run five instances on a single computer with little degradation of performance.
Example: Contoso University wants to migrate 100 GB of mail content per day. They choose to run 10 instances of the MMT on two machines to achieve this performance. They split the user accounts into 10 batches, and run each batch on an instance of the MMT.
Contact migration rate depends on similar factors:
1. Rate of transfer to destination2. Number of MMT instances running3. Number of contacts4. Network bandwidth5. Class of client machine
In internal testing, Microsoft has benchmarked a single instance of the tool migrating 4,800 contacts in 1 hour. This translates to 115,200 contacts/day. By running multiple instances of the MMT in parallel, you can scale your contact migration linearly. Microsoft has run five instances on a single computer with little degradation of performance.
Authentication ModelsFor POP3, Secure Password Authentication (SPA), Authenticated Post Office Protocol (APOP), and USER/PASS are supported (in that order of priority).
SPA is a negotiation of many other authentication models. In this case it depends on what is supported on the client machine and server – and matches what is being used. Typically, this will be NTLM for Windows platforms (on both ends), but it could be Basic (MD5 Hash), Kerberos, or something else.
APOP is an MD5 hash that must be enabled on the server that uses a shared secret and a timestamp.
USER/PASS is just a username and password passed in clear text.
For IMAP4, SPA and LOGIN are supported.
LOGIN is just a username and password in clear text.
Microsoft Live @edu Hotmail MMT v1 Implementation Guide
For both POP3 and IMAP4, Secure Sockets Layer (SSL) connections and negotiation Transport Layer Security (TLS) over non-SSL connections are supported (the latter automatically, when possible).
For Hotmail®, the following are supported:
XML login authentication using the domain user’s Live ID credentials to retrieve a ticket valid for all domain users. This method does not require that the account has been accrued.
Impersonations for domain owners who have configured their site with a certificate, have the GetSLT feature turned on for their domain by the the Windows Live Partner Center, and have fully accrued the user account (country/region, secret question, secret answer, birth year, and accepted Windows Live Terms of Use). This method does not require a user’s Live ID password.
Scenario 1:
Contoso university creates new Hotmail accounts for their users. They use the username/password to log in to the accounts and migrate e-mail content and contacts.
Scenario 2:
Contoso university wants to allow their users to self migrate their e-mail content. They use the username/certificate method to authenticate since they do not know the user’s password.
Note This method will not work if the user has not logged in and accrued information (eg, birth year, secret question). The first method (username/password) must be used if accrual has not completed
Specifying Folder ListsThe partner may want to include and/or exclude certain folders from the migration. The folder lists can be specified on the Windows PowerShell™ command line.
Include: [ * or <names> ]
Exclude: [ * or <names> or none ]
Where * is “all” and <names> can be explicit or contain the * for wildcard.
Example Include Exclude
Move all folders * none
Move Inbox, Sent Items Inbox, Sent items *
Exclude junk folder * Junk
Exclude all folders that start with "Public" * Public*
Microsoft Live @edu Hotmail MMT v1 Implementation Guide
Note Exclude takes precedence over Include, so if “Junk” is listed in both Include and Exclude, it will be excluded in the migration.
Troubleshooting
Failures and RetriesThere are a number of reasons why a mailbox migration would completely or partially fail:
1. Invalid credentials or POP3/IMAP4 server name2. POP3/IMAP4 server is down3. Hotmail® is down4. Attachment is too large5. Mailbox is full6. MMT client fails
Errors are presented to the end user in both of the single-user migration samples. For the bulk migration scenario, it is up to the partner to determine if all mailboxes and content were migrated by examining the summary migration report, an xml file created in the \BulkMigration\Accounts\Reports\ folder.
Extending the MMTAs mentioned above, the partner can create their own extractor and interfaces. Microsoft has tried to make the tool flexible since partners can have different kinds of source e-mail systems and want to enable different types of scenarios.
If your e-mail servers do not support IMAP4 or POP3 or you think these protocols are not enough, you can build your own extractor to get all the information from your database and populate objects within the data model schema. The MMT tool was designed to abstract the data objects for a mailbox. You can see in the source code that the base class is the InternetMailClient. That class is the parent of Pop3Client and Imap4Client. In order to build your own extractor, you would also have to build a class that is a parent of InternetMailClient. What your new class should do is query your e-mail platform for the messages.
Microsoft also understands that not all e-mail migrations will be in bulk and driven by the IT staff. This is why Microsoft supports extending the interface to call the Mail Migration Tool in ways other than Windows PowerShell™. Included within the sample code there is a User Initiated migration sample. This consists of an ASPX page that would be hosted on the partner server that asks for all the details of the
Microsoft Live @edu Hotmail MMT v1 Implementation Guide
account. This can be used as a base to build your own Web pages or other interfaces to communicate to the MMT.
Planning for MigrationAs part of planning for your migration, you need to determine:
The type of migration (bulk or user initiated) The workflow for account provisioning (how will users sign-up) Required changes to DNS Requirements for users to update their e-mail client (settings that need to be configured) How you will access user credential on current (source) e-mail platform and Hotmail® platform
SupportFor problems or issues with the Mail Migration Tool, please follow standard support procedures and open a ticket via the Windows Live Commercial Partner Center using this e-form: https://support.live.com/default.aspx?productkey=wlpc&mkt=en-ww
Additional ResourcesWindows Live Commercial Partner Center
