CSV files for mailbox migration
Applies to: Exchange Server 2013
You can use a CSV file to bulk migrate a large number of user mailboxes. You can specify a CSV file when you use the Exchange admin center (EAC) or the New-MigrationBatch cmdlet in the Exchange Management Shell to create a migration batch. Using a CSV to specify multiple users to migrate in a migration batch is supported in the following migration scenarios:
Moves in on-premises Exchange organizations
Local move: A local move is where you move mailboxes from one mailbox database to another. A local move occurs within a single forest.
Cross-forest enterprise move: In a cross-forest enterprise move, mailboxes are moved to a different forest. Cross-forest moves are initiated either from the target forest, which is the forest that you want to move the mailboxes to, or from the source forest, which is the forest that currently hosts the mailboxes.
Onboarding and offboarding in Exchange Online
Onboarding remote move migration: In an Exchange hybrid deployment, you can move mailboxes from an on-premises Exchange organization to Exchange Online. This is also known as an onboarding remote move migration because you onboard mailboxes to Exchange Online.
Offboarding remote move migration: You can also perform an offboarding remote move migration, where you migrate Exchange Online mailboxes to your on-premises Exchange organization.
Note
Both onboarding and offboarding remote move migrations are initiated from your Exchange Online organization.
Staged Exchange migration: You can also migrate a subset of mailboxes from an on-premises Exchange organization to Exchange Online. This is another type of onboarding migration. You can migrate only Exchange 2003 and Exchange 2007 mailboxes using a staged Exchange migration. Migrating Exchange 2010 and Exchange 2013 mailboxes isn't supported using a staged migration. Prior to running a staged migration, you have to use directory synchronization or some other method to provision mail users in your Exchange Online organization.
IMAP migration: This onboarding migration type migrates mailbox data from an IMAP server (including Exchange) to Exchange Online. For an IMAP migration, you must provision mailboxes in Exchange Online before you can migrate mailbox data.
Note
A cutover Exchange migration doesn't support a using a CSV file because all on-premises user mailboxes are migrated to Exchange Online in a single batch.
Supported attributes for CSV files for bulk moves or migrations
The first row, or header row, of a CSV file used for migrating users lists the names of the attributes, or fields, specified on the rows that follow. Each attribute name is separated by a comma. Each row under the header row represents an individual user and supplies the information required for the migration. The attributes in each individual user row must be in the same order as the attribute names in the header row. Each attribute value is separated by a comma. If the attribute value for a particular record is null, don't type anything for that attribute. However, make sure that you include the comma to separate the null value from the next attribute.
Attribute values in the CSV file override the value of the corresponding parameter when that same parameter is used when creating a migration batch with the EAC or the Exchange Management Shell. For more information and examples, see the section Attribute values in the CSV file override the values for the migration batch.
Tip
You can use any text editor to create the CSV file, but using an application like Microsoft Excel will make it easier to import data and configure and organize CSV files. Be sure to save CSV files as a .csv or .txt file.
The following sections describe the supported attributes for the header row of a CSV file for each migration type. Each section includes a table that lists each supported attribute, whether it's required, an example of a value to use for the attribute, and a description.
Note
- In the following sections, source environment denotes the current location of a user mailbox or a database. Target environment denotes the location that the mailbox will be migrated to or the database that the mailbox will be moved to.
- All mailboxes that are specified in the CSV file will be migrated, even if they are outside of the RBAC scope (for example, an OU) that gives the admin permissions to migrate mailboxes.
Local moves
The following table describes the supported attributes for a CSV file for local moves. For more information, see Manage on-premises moves.
| Attribute | Required or optional | Accepted values | Description |
|---|---|---|---|
| EmailAddress | Required | SMTP address for the user | Specifies the user that will be moved. |
| TargetDatabase | Optional | Database name | Specifies the mailbox database that the user's primary mailbox will be moved to. You can specify a different database in the different rows of the CSV file, which lets you move mailboxes in the same migration batch to different databases. |
| TargetArchiveDatabase | Optional | Database name | Specifies the mailbox database that the user's archive mailbox will be moved to. You can specify a different database in the different rows of the CSV file, which lets you move archive mailboxes in the same migration batch to different databases. Note: If you specify a specific archive database, the archive mailbox (if it exists) will be moved to the same database as the primary mailbox. |
| BadItemLimit | Optional | Unlimited or a non-negative integer from 0 (the default) to a maximum value of 2147483647 |
Specifies the number of bad items to skip if the migration service encounters a corrupted item in the mailbox. If you include this attribute in the CSV file, it will override the default value or a value you specify if you include the BadItemLimit parameter when creating the migration batch using the EAC or the Exchange Management Shell. Tip: We recommend that you use the default value of 0 and only increase the bad item limit for a particular user if the move or migration for that user fails. |
| MailboxType | Optional | Use one of the following values:
|
Specifies whether to move the user's primary mailbox, archive mailbox, or both. |
Onboarding remote move migrations in a hybrid deployment
In a hybrid deployment, you can move mailboxes from an on-premises Exchange organization to Exchange Online. When onboarding mailboxes, the migration batch is created in the Exchange Online organization and initiated by an Exchange Online administrator. For more information, see Move mailboxes between on-premises and Exchange Online organizations in hybrid deployments.
The following table describes the supported attributes for a CSV file for onboarding remote move migrations.
| Attribute | Required or optional | Accepted values | Description |
|---|---|---|---|
| EmailAddress | Required | SMTP address for the user | Specifies the email address for the mail-enabled user in the Exchange Online organization that corresponds to the on-premises user mailbox that will be migrated. |
| BadItemLimit | Optional | Unlimited or a non-negative integer from 0 (the default) to a maximum value of 2147483647 |
Specifies the number of bad items to skip if the migration service encounters a corrupted item in the mailbox. If you include this attribute in the CSV file, it will override the default value or the value you specify if you include the BadItemLimit parameter when creating the migration batch using the EAC or the Exchange Management Shell. Tip: We recommend that you use the default value of 0 and only increase the bad item limit for a particular user if the move or migration for that user fails. |
| LargeItemLimit | Optional | Unlimited or a non-negative integer from 0 (the default) to a maximum value. |
Specifies the number of large items in the user's mailbox that will be skipped. When the number of large items exceeds this value, the migration for the mailbox fails. The default value is 0, which means that the migration fails if the mailbox contains any large items. When onboarding mailboxes to Exchange Online, items up to 35 MB are migrated. |
| MailboxType | Optional | Use one of the following values:
|
Specifies whether to move the user's primary mailbox, archive mailbox, or both. |
Cross-forest enterprise moves and offboarding remote move migrations in a hybrid deployment
As previously stated, cross-forest moves are initiated either from the target forest or from the source forest. Offboarding remote move migrations are initiated from your Exchange Online organization. For more information, see:
- Prepare mailboxes for cross-forest move requests
- Move mailboxes between on-premises and Exchange Online organizations in hybrid deployments
The following table describes the supported attributes for a CSV file for cross-forest enterprise moves and for offboarding remote move migrations in an Exchange hybrid deployment.
| Attribute | Required or optional | Accepted values | Description |
|---|---|---|---|
| EmailAddress | Required | SMTP address for the user | For cross-forest enterprise moves, this specifies the mailbox or mail-enabled user in the source forest. For offboarding remote move migrations, it specifies the Exchange Online mailbox. |
| TargetDatabase | Required for offboarding remote move migrations and for cross-forest enterprise moves that are initiated from the source forest. Alternatively, this attribute can be specified when creating the migration batch in the EAC or using the Exchange Management Shell. This attribute is optional for cross-forest enterprise moves that are initiated from the target forest. |
Database name | Specifies the mailbox database in the target forest that the user's primary mailbox will be moved to. You can specify a different database in the different rows of the CSV file, which lets you move mailboxes in the same migration batch to different databases. |
| TargetArchiveDatabase | Optional | Database name | Specifies the mailbox database in the target forest that the user's archive mailbox will be moved to. You can specify a different database in the different rows of the CSV file, which lets you move archive mailboxes in the same migration batch to different databases. |
| BadItemLimit | Optional | Unlimited or a non-negative integer from 0 (the default) to a maximum value of 2147483647 |
Specifies the number of bad items to skip if the migration service encounters a corrupted item in the mailbox. If you include this attribute in the CSV file, it will override the default value or the value you specify if you include the BadItemLimit parameter when creating the migration batch using the EAC or the Exchange Management Shell. Tip: We recommend that you use the default value of 0 and only increase the bad item limit for a particular user if the move or migration for that user fails. |
| LargeItemLimit | Optional | Unlimited or a non-negative integer from 0 (the default) to a maximum value. |
Specifies the number of large items in the user's mailbox that will be skipped. When the number of large items exceeds this value, the migration for the mailbox fails. The default value is 0, which means that the migration fails if the mailbox contains any large items. When onboarding mailboxes to Exchange Online, items up to 35 MB are migrated. |
| MailboxType | Optional | Use one of the following values:
|
Specifies whether to move the user's primary mailbox, archive mailbox, or both. |
Staged Exchange migrations
You have to use a CSV file to identify the group of users for a migration batch when you want to use a staged Exchange migration to migrate Exchange 2003 and Exchange 2007 on-premises mailboxes to Exchange Online. There isn't a limit for the number of mailboxes that you can migrate to the cloud using a staged Exchange migration. However, the CSV file for a migration batch can contain a maximum of 1,000 rows. To migrate more than 1,000 mailboxes, you have to create additional CSV files, and then use each one to create a new migration batch. For more information about staged Exchange migrations, see Migrate mailboxes to Exchange Online with a staged migration.
The following table describes the supported attributes for a CSV file for a staged Exchange migration.
| Attribute | Required or optional | Accepted values | Description |
|---|---|---|---|
| EmailAddress | Required | SMTP address for the user | Specifies the email address for the mail-enabled user (or a mailbox if you're retrying the migration) in Exchange Online that corresponds to the on-premises user mailbox that will be migrated. Mail-enabled users are created in Exchange Online as a result of directory synchronization or another provisioning process. The email address of the mail-enabled user must match the WindowsEmailAddress property for the corresponding on-premises mailbox. |
| Password | Optional | A password has to have a minimum length of eight characters, and satisfy any password restrictions that are applied to your Microsoft 365 or Office 365 organization. | This password is set on the user account when the corresponding mail-enabled user in Exchange Online is converted to a mailbox during the migration. |
| ForceChangePassword | Optional | True or False |
Specifies whether a user must change the password the first time they sign in to their Exchange Online mailbox. Note: If you've implemented a single sign-on solution by deploying Active Directory Federation Services 2.0 (AD FS 2.0) in your on-premises organization, you must use |
IMAP migrations
A CSV file for an IMAP migration batch can have maximum of 50,000 rows. But it's a good idea to migrate users in several smaller batches. For more information about IMAP migrations, see the following topics:
The following table describes the supported attributes for a CSV file for an IMAP migration.
| Attribute | Required or optional | Accepted values | Description |
|---|---|---|---|
| EmailAddress | Required | SMTP address for the user. | Specifies the user ID for the user's Exchange Online mailbox |
| UserName | Required | String that identifies the user on the IMAP messaging system, in a format supported by the IMAP server. | Specifies the logon name for the user's account in the IMAP messaging system (the source environment). In addition to the user name, you can use the credentials of an account that has been assigned the necessary permissions to access mailboxes on the IMAP server. For more information, see CSV files for IMAP migration batches. |
| Password | Required | Password string. | Specifies the password for the user account specified by the UserName attribute. |
Attribute values in the CSV file override the values for the migration batch
Attribute values in the CSV file override the value of the corresponding parameter when that same parameter is used when creating a migration batch with the EAC or the Exchange Management Shell. If you want the migration batch value to be applied to a user, you would leave that cell blank in the CSV file. This lets you mix and match certain attribute values for selected users in one migration batch.
For example, let's say you create a batch in the Exchange Management Shell for a cross-forest enterprise move to move users' primary and archive mailboxes to the target forest with the following Exchange Management Shell command.
New-MigrationBatch -Name CrossForestBatch1 -SourceEndpoint ForestEndpoint1 -TargetDeliveryDomain forest2.contoso.com -TargetDatabases @(EXCH-MBX-02,EXCH-MBX-03) -TargetArchiveDatabases @(EXCH-MBX-A02,EXCH-MBX-A03) -CSVData ([System.IO.File]::ReadAllBytes("C:\Users\Administrator\Desktop\CrossForestBatch1.csv")) -AutoStart
Note
Because the default is to move primary and archive mailboxes, you don't have to explicitly specify it in the Exchange Management Shell command.
A portion of the CrossForestBatch1.csv file for this migration batch looks like this:
EmailAddress,TargetDatabase,TargetArchiveDatabase
user1@contoso.com,EXCH-MBX-01,EXCH-MBX-A01
user2@contoso.com,,
user3@contoso.com,EXCH-MBX-01,
...
Because the values in the CSV file override the values for the migration batch, the primary and archive mailboxes for user1 are moved to EXCH-MBX-01 and EXCH-MBX-A01, respectively, in the target forest. The primary and archive mailboxes for user2 are moved to either EXCH-MBX-02 or EXCH-MBX-03. The primary mailbox for user3 is moved to EXCH-MBX-01 and the archive mailbox is moved to either EXCH-MBX-A02 or EXCH-MBX-A03.
In another example, let's say you create a batch for an onboarding remote move migration in a hybrid deployment to move archive mailboxes to Exchange Online with the following command.
New-MigrationBatch -Name OnBoarding1 -SourceEndpoint RemoteEndpoint1 -TargetDeliveryDomain cloud.contoso.com -CSVData ([System.IO.File]::ReadAllBytes("C:\Users\Administrator\Desktop\OnBoarding1.csv")) -MailboxType ArchiveOnly -AutoStart
But you also want to move the primary mailboxes for selected users, so a portion of the OnBoarding1.csv file for this migration batch would look like this:
EmailAddress,MailboxType
user1@contoso.com,
user2@contoso.com,
user3@cloud.contoso.com,PrimaryAndArchive
user4@cloud.contoso.com,PrimaryAndArchive
...
Because the value for mailbox type in the CSV file overrides the values for the MailboxType parameter in the command to create the batch, only the archive mailbox for user1 and user2 is migrated to Exchange Online. But the primary and archive mailboxes for user3 and user4 are moved to Exchange Online.