Prepare a CSV File to Migrate E-mail from an IMAP Server
Applies to: Office 365 for professionals and small businesses, Office 365 for enterprises, Live@edu
Topic Last Modified: 2011-11-23
The CSV file you use to migrate the contents of users' mailboxes contains a row for each user. Each row contains information about the users' cloud-based mailbox and IMAP mailbox, which Microsoft Exchange uses to process the migration.
The CSV file can contain up to 50,000 rows, one row for each user, and can be as large as 10 MB. But it's a good idea to migrate users in several smaller batches.
If you plan to migrate lots of users, decide which ones to include in each batch. For example, if you have 10,000 accounts to migrate, you could run four batches with 2,500 users each, or you could divide the batches alphabetically, by user type, such as faculty, students, and alumni, by class, such as freshman, sophomore, junior, and senior, or in other ways that meet your organization's needs.
Tip One strategy is to create cloud-based mailboxes and migrate e-mail for the same group of users. For example, if you import 2,000 new users to your cloud-based e-mail organization, create a migration batch for those same 2,000 users. This is an effective way to organize and manage your migration from an on-premises messaging system to the cloud.
In the CSV file, you have to provide the username and password for the user's on-premises account. This enables the migration process to access the account during the migration process. There are two ways to do this:
- Use end-user credentials This requires that you obtain users' passwords or that you change their passwords to a value that you know so you can include it in the CSV file.
Tip If you use this option, prevent users from changing the password of the on-premises account. If users change their password after the initial migration, subsequent synchronizations between the mailboxes on the IMAP server and cloud-based mailboxes will fail.
- Use super-user or administrator credentials This requires that you use an account in your IMAP messaging system that has the necessary rights to access all user mailboxes. In the CSV file, you use the credentials for this account for each row. To learn whether your IMAP server supports this approach and how to enable it, see the documentation for your IMAP server.
Tip We recommend using administrator credentials because it doesn't affect or inconvenience users. For example, it won't matter if users change their passwords after the initial migration.
Here are the required attributes for each user:
- EmailAddress specifies the Windows Live ID for the user's cloud-based mailbox.
- UserName specifies the user logon name for the user's mailbox on the IMAP server.
- Password is the password for the user's account in the IMAP messaging system.
The migration will fail if any one of these attributes isn't included in the header row of the CSV file. Also, be sure to 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 the CSV file. In this example, end-user credentials are used to migrate three mailboxes:
EmailAddress,UserName,Password email@example.com,terry.adams,1091990 firstname.lastname@example.org,ann.beebe,2111991 email@example.com,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.
You can use the username and password of an administrator account in the UserName and Password fields for each row of the CSV file. The username for administrator credentials is a combination of the username for the person whose e-mail is being migrated and the username for an administrator account that has permission to access all user mailboxes. The supported format for administrator credentials is different depending on the IMAP server you're migrating e-mail from. For more information about how to use administrator 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.
The following sections explain how to format the administrator credentials in the CSV file that you use to migrate e-mail from different types of IMAP servers.
If you're migrating e-mail from the IMAP implementation for Microsoft Exchange, use the format Domain/Admin_UserName/User_UserName for the UserName attribute in the CSV file. Let's say you're migrating e-mail from Exchange for Terry Adams, Ann Beebe, and Chris Cannon. You have a mail administrator account, where the username is mailadmin and the password is P@ssw0rd. Here's what your CSV file would look like:
EmailAddress,UserName,Password firstname.lastname@example.org,contoso-students/mailadmin/terry.adams,P@ssw0rd email@example.com,contoso-students/mailadmin/ann.beebe,P@ssw0rd firstname.lastname@example.org,contoso-students/mailadmin/chris.cannon,P@ssw0rd
For IMAP servers that support Simple Authentication and Security Layer (SASL), such as a Dovecot IMAP server, use the format Admin_UserName*User_UserName where the asterisk ( * ) is a configurable separator character. Let's say you're migrating those same users' e-mail from a Dovecot IMAP server using the administrator credentials mailadmin and P@ssw0rd. Here's what your CSV file would look like:
EmailAddress,UserName,Password email@example.com,mailadmin*terry.adams,P@ssw0rd firstname.lastname@example.org,mailadmin*ann.beebe,P@ssw0rd email@example.com,mailadmin*chris.cannon,P@ssw0rd
If you're migrating e-mail from Mirapoint Message Server, use the format #user@domain#Admin_UserName# for the administrator credentials. To migrate e-mail from Mirapoint using the administrator credentials mailadmin and P@ssw0rd, your CSV file would look like:
EmailAddress,UserName,Password firstname.lastname@example.org,#email@example.com#mailadmin#,P@ssw0rd firstname.lastname@example.org,#email@example.com#mailadmin#,P@ssw0rd firstname.lastname@example.org,#email@example.com#mailadmin#,P@ssw0rd
Some IMAP servers, such as Courier IMAP, don't support using administrator credentials to migrate mailboxes to the cloud. To use administrator credentials to migrate mailboxes, you can configure your IMAP server to use virtual shared folders. Virtual shared folders allow administrators to use the administrator's login credentials to access user mailboxes on the IMAP server. For more information about how to configure virtual shared folders for Courier IMAP, see Shared Folders.
To migrate mailboxes after you set up virtual shared folders on your IMAP server, you have to include the optional attribute UserRoot in the CSV file. This attribute specifies the location of each user's mailbox in the virtual shared folder structure on the IMAP server.
Here's an example of a CSV file that contains the UserRoot attribute:
EmailAddress,UserName,Password,UserRoot firstname.lastname@example.org,mailadmin,P@ssw0rd,/users/terry.adams email@example.com,mailadmin,P@ssw0rd,/users/ann.beebe firstname.lastname@example.org,mailadmin,P@ssw0rd,/users/chris.cannon