Import New Exchange Online Users with a CSV File

Applies to: Office 365 for professionals and small businesses, Office 365 for enterprises, Live@edu

You can use the Exchange Control Panel and a comma separated value (CSV) file to provision large numbers of new users. Bulk provisioning is an effective way to:

• Quickly provision users in your cloud-based e-mail organization for testing and evaluation.
• Provision a new group of users on a regular schedule, such as before the start of a new quarter or semester.

The CSV import file contains a row for each new user. Each row contains the information that the import process uses to create a mailbox for the user. For more information, see Prepare a CSV File to Import New Exchange Online Users.

This topic explains the following:

• Overview of the import process
• How long does it take to import users?
• What is in the ImportErrors.csv file?
• Best practices
• Next steps

Watch this demo to learn how to import new users

Note If you've recently completed the Live@edu enrollment, you can create up to 450 mailboxes but no more in the first business day after your MX record is detected. The reason is that we need one business day to confirm that you are an eligible educational institution. After confirmation is complete, the 450-mailbox limit is lifted.

Top of page

Overview of the import process

Here's how the user import process works:

1. In the Exchange Control Panel, select Manage My Organization > Users & Groups > Mailboxes > Import users.
   Note   If an import process or e-mail migration is currently running, Import users doesn’t appear because only one import or migration process for your domain can run at a time. When the current process is finished, the Import users button is displayed so that you can start a new import.
2. Click Browse to select a CSV file, click Open, and then click Next.
3. The Exchange Control Panel displays a message that says the CSV file is being uploaded and verified. During this process, Microsoft Exchange checks the CSV file for two types of errors:
   • Critical errors   The import process checks the CSV file for the following:
     • It uses comma separated formatting.
     • It isn't empty, but doesn't contain more than 50,000 rows.
     • It includes the required attributes in the header row.
     • It contains the Password attribute.
     • It contains only attributes that are supported and recognized by the import process.
     • It contains rows with the same number of attributes as the header.
     If any of these conditions isn't true, Microsoft Exchange terminates the import process and displays an error that explains the reason for the failure. You have to fix the critical error and restart the import process.
   • Data validation errors   The import process performs a preliminary data validation check to verify that the data in each column in the CSV file meets the property definition for the corresponding attribute. For example, it checks the e-mail address in each row to verify the address uses a valid SMTP address format. To see what other data validation checks are performed, see Troubleshoot Errors When Importing Users.
4. If no critical errors are found, the Exchange Control Panel displays the Import Users page saying that data validation is complete. If no data validation errors are found, click Import to start the import process.
   If data validation errors are found, the Import Users page displays a warning message stating how many rows had errors. Click Show error details to display the Data Validation Report for Import Users, which contains details about each validation error. At this point, you have two options:
   • Click Start Over, fix the validation errors using the details in the Data Validation Report, and then resubmit the CSV file.
   • Click Import to start the import process. User accounts won't be created for rows with validations errors. Details from the data validation report are included in the ImportErrors.csv file sent to you after the import process is completed (see step 9). Use the information in this file to fix the rows with validation errors and then start a new user import and submit the revised CSV file.
     Note   There may be a delay before the import process starts because the server process running on Microsoft Exchange may be busy processing import requests for organizations.
5. After the import process starts, the Import in Progress status window is displayed on the Mailboxes tab with a message saying the import process will begin shortly. This window shows the name of the CSV file being processed, the number of new mailbox requests, which corresponds to the number of rows in the CSV file, the number of new mailboxes that have been created, and the number of mailboxes that have failed.
   You can also use the status window to stop the import process if necessary. For more information, see Status of the Import Users in Progress.
6. When the import process is finished, Microsoft Exchange sends the administrator who submitted the CSV import file an e-mail that contains the final results of the import process. This information includes:
   • The start time of the import process.
   • The total duration of the import process.
   • The total number of mailboxes processed, the number of mailboxes successfully created, and the number that failed.
   • A link to download a CSV file (named ImportErrors.csv) that contains a row for each user that couldn't be imported and the reason for the failure. If there are no failures, the e-mail doesn't include a link to this file.

Top of page

How long does it take to import users?

The load on the computers running Microsoft Exchange in the datacenter, network traffic, and other factors can affect how long it takes to import new users. Also, there may be a short delay before the import process actually starts because the server process running on Microsoft Exchange may be busy processing import user requests for other organizations.

What is in the ImportErrors.csv file?

As explained earlier, if errors in the CSV file prevent users from being imported, Microsoft Exchange includes a link to download the ImportErrors.csv file in the e-mail that is sent to the administrator who submitted the import request. The file contains a row with the submitted attributes for each failed user. It also contains an attribute in the header row named Failure Reason and a corresponding field in each row that explains why that row failed.

Here's an example of an ImportErrors.csv file:

Failure Reason,Name,EmailAddress,FirstName,LastName,Password
"The e-mail address 'terrya@contoso.edu' is already in use by the user ./Microsoft Exchange Hosted Organizations/contoso.edu/terrya'.",adamsta0109,terrya@contoso.edu,Terry,Adams,1091990
"The user 'beebeab0211' already exists in the organization.",beebeab0211,annb@contoso.edu,Ann,Beebe,2111991
"Password is too short.",garciadg0726,debrag@fineartschool.edu,Debra,Garcia,72719
"In row number 4, column 'lastname' is blank. This column is required. Please edit the CSV file and submit it again.",kolak1123,aylak@fineartschool.edu,Ayla,,11231988

Use the ImportErrors.csv file to fix errors and import users

You can use the ImportErrors.csv file to fix errors and import the users that failed. For each row, use information in the Failure Reason column to resolve the problem that caused the row to fail. Then use that same ImportErrors.csv file to submit a new import user request. The import process will ignore the Failure Reason column. You can also delete the Failure Reason column before you resubmit the fixed CSV import file.

Top of page

Best practices

• Use your CSV file to test the import of a small batch of users and user data before you import a large number of users   This lets you:
  • Troubleshoot potential problems to minimize mistakes when you import a large batch of users.
  • Test any optional attributes that you want to use in the header row.
  • Verify that you are using the correct data format for each attribute.
  • Verify that you can export data in the appropriate format from your student records database and that you have mapped it correctly to the appropriate attribute in the header row.
• Verify that attribute values appear in the shared address book the way you intend   After you import a small group of test users, sign in to your account, and see how the attribute values for each user are displayed in the shared address book. You may want to make changes, or add or remove an optional attribute from the header row.
• Run smaller batches instead of one large batch   Although a CSV file can contain up to 50,000 rows, it could take up to five days or longer to import this many users in one batch. If you want to provision a large number of users, consider using several smaller batches instead of one large batch. This approach lets you validate results, and if necessary, re-submit, in smaller batches instead waiting for one large batch to be processed.
• Require users to change their password   For Live@edu organizations, it's a good idea to use the ForceChangePassword attribute when you import new users. This will create a Windows Live ID that requires new users to change their password after they sign in for the first time. This is a security best practice to help ensure only users know the password for their accounts.
  Note   The option to require users to change their password isn't available for Microsoft Online e-mail organizations.
• Use the DisplayName attribute   Unless you have a policy of excluding users' display names in the shared address book and the Exchange Control Panel, consider using the optional DisplayName attribute in the CSV import file. By setting a specific display name for each user, you ensure that each user is easy to identify in the shared address book. The Name attribute that Microsoft Exchange uses as the display name if you don't set the optional DisplayName attribute may not be clearly recognizable by users.
  Tip   If you want to use LastName, FirstName as the format for display names, do the following when you prepare the CSV import file:
  • If you are using a text editor, include double quotation marks in the DisplayName attribute value. For example, use "Adams, Terry" for a user named Terry Adams.
  • If you are using Excel, don't include double quotation marks because Excel automatically adds quotation marks when you save it as a CSV file. If you add quotation marks in Excel, quotation marks are included in the user's display name in the shared address book.

Top of page

Next steps

If you have a Microsoft Office 365 e-mail organization, you must assign licenses to new mailboxes or they will be disabled when the grace period ends. For more information, see Assign a License to New Mailboxes in Office 365.