Create and Configure Recipients with the CSV

Download and use the CSV_Parser.ps1 Windows PowerShell script to add new users, update existing users, or delete existing users. The script, which uses a comma separated value (CSV) file to specify users, is a great way to create and configure many users at one time.

Note You can also create many new users with a CSV file in the Exchange Control Panel. For more information, see Import New Exchange Online Users with a CSV File.

Use the script for the following user types:

Mailbox users Mailbox users are users in your cloud-based domain that have a mailbox and a corresponding Windows Live ID.
Mail contacts Mail contacts, also known as external contacts, don't have a Windows Live ID or a mailbox in your domain. For the cloud-based service, mail contacts are users outside your organization. However, their contact information includes an e-mail address that can be displayed in your address book.
Mail users Mail users also don't have a mailbox in your domain. However, for the cloud-based service, mail users are users inside your organization, and they can have a Windows Live ID. For example, they can be users in your organization who have on-premises e-mail accounts.

For a more detailed explanation, see the following sections in this topic:

Options for the CSV file
- Important attributes for the CSV file
- Optional attributes for the CSV file
Options for the CSV_Parser.ps1 script
How do you use the CSV_Parser.ps1 script?
Troubleshoot the CSV_Parser.ps1 script
Unsupported attributes

Before you begin

To learn how to install and configure Windows PowerShell and connect to the service, see Use Windows PowerShell.

You don't have to connect Windows PowerShell to the cloud-based service before you run the script. The script connects for you.

Download the script

Download the CSV_Parser.ps1 Windows PowerShell script here.

After you download the script file, perform the following steps:

Right-click the script file, and select Properties.
On the General tab, in the Security section that has the text "This file came from another computer and might be blocked to help protect this computer," click Unblock. If there is no Security section, don't worry about it.
Click OK.

Options for the CSV file

You can use any text editor, or an application like Microsoft Office Excel, to create the CSV file. Format the file as described in the "CSV file format" section of this topic and save the file with the extension ".csv".

Note:
If the CSV file contains non-ASCII characters, make sure to save the CSV file with UTF-8 encoding. Depending on the application, saving the CSV file with UTF-8 encoding may be easier when the system locale of the computer matches the language used in the CSV file. Also, if you use Excel to create or modify the CSV file, don't include double quotation marks in the cell values. Excel automatically adds double quotation marks to all cell values that contain spaces when the file is saved as a CSV file. You can examine the CSV file in Notepad or another text editor to confirm that the values don't contain extra double quotation marks.

Note:

If the CSV file contains non-ASCII characters, make sure to save the CSV file with UTF-8 encoding. Depending on the application, saving the CSV file with UTF-8 encoding may be easier when the system locale of the computer matches the language used in the CSV file.
Also, if you use Excel to create or modify the CSV file, don't include double quotation marks in the cell values. Excel automatically adds double quotation marks to all cell values that contain spaces when the file is saved as a CSV file. You can examine the CSV file in Notepad or another text editor to confirm that the values don't contain extra double quotation marks.

The first row, or header row, of the CSV file 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 Windows Live ID and the cloud-based mailbox and address book listing. 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.

CSV file format

Here's an example of the correct format for a CSV file. In this example, two mailbox users are being provisioned: one for Tamara Johnston and one for Ayla Kol.

Copy

Action,Type,Name,EmailAddress,Password,FirstName,LastName,DisplayName
Add,Mailbox,Tamara Johnston,TamaraJ@students.contoso.edu,P@ssw0rd,Tamara,Johnston,Tamara Johnston
Add,Mailbox,Ayla Kol,Aylak@students.contoso.edu,P@ssw0rd,Ayla,Kol,Ayla Kol

Important attributes for the CSV file

This table lists the important attributes used in the CSV file. Many of these attributes are always required.

Attribute name	Required/Optional	Description
Action	Always required	Action refers to the type of procedure being performed. Valid options are: Add This value creates new users in your domain. If you attempt an Add action, and the Name attribute and the Type attribute that you specify matches the Name attribute and Type attribute of an existing user, the `CSV_parser.ps1` script automatically converts the Add action to an Update action on the existing user. If the Name attributes match, but the Type attributes are different, the Add action fails. If you attempt an Add action to create mailbox users or mail users, you may accidentally specify an unmanaged Windows Live ID, and the Add action will fail. An unmanaged ID, also called an e-mail as sign-in ID (EASI ID) is a Windows Live ID created by a user before you enrolled your domain in the cloud-based service. You can use the ImportLiveID or EvictLiveID attributes to create the user. For more information about unmanaged Windows Live IDs, see Import or Evict Existing Windows Live IDs in Live@edu. Update This value updates existing users in your domain. Caution If you define an attribute in the header row, but specify a null value for the attribute for the user in an Update action, the existing value of the attribute is removed from the user. Delete This value deletes existing users from your domain. By default, the mailbox and the associated Windows Live ID are removed from use. This removes the user's access to all data associated with the Windows Live ID, such as Xbox Live points and Zune points, and data on Windows Live Spaces, Windows Live Groups, and Windows Live SkyDrive. You can keep the Windows Live ID using the KeepWindowsLiveID attribute. PasswordReset This value resets the password for an existing user. When you use this action, the only attributes that you specify are Name and Password. All other attributes are ignored. Important Avoid combining Add actions and Update actions in the same CSV file. And remember: if you define an attribute in the header row but specify a null value for the attribute for the user in an Update action, the existing value of the attribute is removed from the user.
Type	Always required	Type specifies the user type. Valid entries are: Mailbox This value specifies mailbox users in your domain that have a mailbox and a corresponding Windows Live ID. MailContact This value specifies a mail contact, a user outside your domain that doesn't have a Windows Live ID or a mailbox in your domain, but can receive e-mail messages at an external e-mail address. The e-mail address can't be in an accepted domain of the cloud-based organization. Mail contacts are also known as external contacts. MailUser This value specifies a mail user, a user that doesn't have a mailbox in your domain. The e-mail address must exist in an accepted domain of the cloud-based organization. Use MailUser for members of your organization who don't have a cloud-based mailbox. For example, use MailUser for the faculty and staff of a university where only the students and alumni have cloud-based mailboxes. The `CSV_Parser.ps1` script creates mail users with a Windows live ID. You can create a mail user without a Windows Live ID by using the New-MailUser cmdlet. For more information, see Create Mail Users.
Name	Always required	Name specifies an identifier for the user. When you create new mailbox users or mail users, the value of Name is used as the name of the Windows Live ID. The value of Name must be unique in your domain. The Name attribute is important for Windows PowerShell operations on cloud-based users, but the value of the Name attribute isn't visible outside Windows PowerShell. The DisplayName attribute is modifiable for existing users and is visible in the shared address book. Note Make sure the value that you use for Name is unique in your cloud-based organization. If you create two accounts with the same value of Name but different Windows Live IDs, there may be problems properly associating the Windows Live ID with the correct mailbox.
DisplayName	Optional for Add and Update actions Not used with Delete actions	DisplayName specifies how the user name is displayed in the address book and in the Exchange Control Panel. If you don't specify a value for DisplayName when you create new users, the value of EmailAddress is used for DisplayName. To create the display name "Last, First", enclose the value in double quotation marks. If you use Excel to create or modify the CSV file, don't include the double quotation marks in the cell values.
FirstName	Optional for Add and Update actions Not used with Delete actions	FirstName specifies the first name that is listed for the user in the address book. When you create new mailbox users or mail users, the value of FirstName is also used as the first name of the Windows Live ID.
LastName	Optional for Add and Update actions Not used with Delete actions	LastName specifies the last name that is listed for the user in the address book. When you create new mailbox users or mail users, the value of LastName as also used as the last name of the Windows Live ID.
EmailAddress or WindowsLiveID	Required for Add and Update actions Not used with Delete actions	EmailAddress and WindowsLiveID are interchangeable. Don't use EmailAddress and WindowsLiveID in the same CSV file. EmailAddress specifies the e-mail address of a new user. When you create new mailbox users or mail users, the EmailAddress attribute is used as the primary e-mail address and is used to create the corresponding Windows Live ID. The value of EmailAddress must be unique in the cloud-based organization. For mailbox users and mail users, the value of EmailAddress must be in an accepted domain of the cloud-based organization. For mail contacts, the value of EmailAddress can't be in an accepted domain of the cloud-based organization. You can't use the CSV_Parser.ps1 script to update the primary e-mail address or Windows Live ID for an existing user.
FederatedIdentity	Required for Add actions on mailbox users and mail users in federated domains Not used with Update or Delete actions	FederatedIdentity is used in federated domains to associate an on-premises account with a cloud-based mailbox or mail user.
EmailAddressN where N is an integer from 2 through 5.	Optional for Update actions Not used with Add or Delete actions	EmailAddressN specifies up to 4 additional e-mail addresses, known as proxy addresses for the user. For mailbox users and mail users, the proxy address must be in an accepted domain of the cloud-based organization. For mail contacts, the proxy address can't be in an accepted domain of the cloud-based organization.
Password	Required for Add actions on mailbox users and mail users Optional for Update actions on mailbox users Not used with Delete actions	Password is the Windows Live ID password for a mailbox user or mail user. The Password attribute is required when you create new mailbox users or mail users, and can be used optionally to reset an existing mailbox user's password. To force a user to change their password after they log on, use the ForceChangePassword attribute. For more information about passwords, see Password Guidelines.
ForceChangePassword or ResetPasswordOnNextLogon	Optional for Add and Update actions on mailbox users Not used with Delete actions	ForceChangePassword and ResetPasswordOnNextLogon are interchangeable. Don't use ForceChangePassword and ResetPasswordOnNextLogon in the same CSV file. ForceChangePassword is available only in the `CSV_parser.ps1` script when you are creating or updating mailbox users. When ForceChangePassword is set to `1`, or if the ForceChangePassword attribute isn't defined in the header row, new users must change their password after they log on for the first time. When ForceChangePassword is set to `0`, new users aren't required to change their password after they log on for the first time.
MailboxPlan	Optional for Add actions on mailbox users Not used with Update or Delete actions	MailboxPlan is only available in the `CSV_parser.ps1` script when you are creating new mailbox users. If you don't specify a value for MailboxPlan, the default mailbox plan for your organization is used. Typical values are DefaultMailboxPlan and GalDisabledMailboxPlan. For more information about mailbox plans, see Mailbox Plans.
EvictLiveID	Optional for Add actions on mailboxes and mail users Not used with Update or Delete actions	EvictLiveID is only available when you create mailboxes or mail users. Use this attribute to create the user in the event you encounter an EASI ID that matches the e-mail address of the new user you're trying to create. When set to `Y`, the Windows Live ID and all its existing settings, including the password, are preserved. However, the Windows Live ID is removed from your cloud-based domain and placed in a forced rename state. For more information, see Import or Evict Existing Windows Live IDs in Live@edu. When you evict the Windows Live ID from your domain, you can create a new Windows Live ID with the same name, but the password must be different than the password of the evicted Windows Live ID. If an EASI ID is encountered during an Add action, and you didn't specify an EvictLiveID or ImportLiveID value of `Y`, the Add action will fail for that user.
ImportLiveID	Optional for Add actions on mailbox users and mail users Not used with Update or Delete actions	ImportLiveID is only available when you create mailboxes or mail users. Use this attribute to create a user in the event you encounter an EASI ID that matches the e-mail address of the new user you're trying to create. Note ImportLiveID isn't supported in federated domains. When set to `Y`, the Windows Live ID and all of its existing settings, including the password, are preserved, and it's associated with the new mailbox or mail user that you create in your domain. For more information, see Import or Evict Existing Windows Live IDs in Live@edu. After you import the Windows Live ID into your cloud-based organization, you can't evict the Windows Live ID. Generally, we recommend that you don't import EASI IDs into your cloud-based organization. Also, if you import the Windows Live ID into your cloud-based organization, the value of Password is ignored. If an EASI ID is encountered during an Add action, and you didn't specify an EvictLiveID or ImportLiveID value of `Y`, the Add action will fail for that user.
KeepWindowsLiveID	Optional for Delete actions on mailbox users and mail users Not used with Add or Update actions	KeepWindowsLiveID is only available when you delete mailboxes or mail users. When set to `Y`, the Windows Live ID that is associated with the deleted user is preserved. The user can still access all data that's associated with their Windows Live ID, such as Xbox Live points and Zune points, and data on Windows Live Spaces, Windows Live Groups, and Windows Live SkyDrive. If the value of KeepWindowsLiveID isn't `Y`, the Windows Live ID of the removed mailbox is removed from use. The user loses access to all data associated with their Windows Live ID. However, you can typically recover a deleted mailbox and the associated Windows Live ID within 30 days. For more information, see Recover a Deleted Mailbox. Note In federated domains, the Windows Live ID is always preserved, so you don't need to use the KeepWindowsLiveID attribute.

Top of page

Optional attributes for the CSV file

This table lists optional attributes you can use in the CSV file. If you don’t supply values for these attributes, they are left blank. None of these attributes are used with Delete actions.

Attribute name	Description
City	City specifies the city that is listed for the user in the address book.
Company	Company specifies the company name that is listed for the user in the address book.
CountryorRegion	CountryorRegion specifies the ISO 3166 two-letter country code or the name of the country or region that is listed for the user in the address book. You can find the valid values for the CountryorRegion attribute in the Country / Region field in the Contact Information section of the account properties in the Exchange Control Panel.
CustomAttributeN where N is an integer from 1 through 15.	This parameter specifies the Custom Attribute N property where N is an integer from 1 through 15. The Custom Attribute N properties aren't visible in the Exchange Control Panel or the address book. However, you can use the Custom Attribute N values as filters in Windows PowerShell operations, such as creating dynamic distribution groups. For more information, see Dynamic Distribution Groups.
Department	Department specifies the department that is listed for the user in the address book.
Fax	Fax specifies the fax number that is listed for the user in the address book.
HomePhone	HomePhone specifies the home phone number that is listed for the user in the address book.
Initials	Initials specifies the middle initial that is listed for the user in the address book.
MobilePhone	MobilePhone specifies the cell phone number that is listed for the user in the address book.
Notes	The Notes field specifies additional information that is listed for the user in the address book.
Office	Office specifies the office location that is listed for the user in the address book.
Phone	Phone specifies the work phone number that is listed for the user in the address book.
PostalCode	PostalCode specifies the postal code that is listed for the user in the address book.
StateorProvince	StateorProvince specifies the state or province that is listed for the user in the address book.
StreetAddress	StreetAddress specifies the street address that is listed for the user in the address book.
Title	Title specifies the title that is listed for the user in address book.
WebPage	WebPage specifies the Web page address that is listed for the user in the address book.

Top of page

Options for the CSV_Parser.ps1 script

Parameter	Required	Description
LiveCredential	Required	The LiveCredential parameter specifies the Windows Live ID and password of an Exchange Online administrator account in your cloud-based domain. To specify a value for the LiveCredential parameter, store the Windows Live ID credentials in a variable before you run the `CSV_Parser.ps1` script, for example, `$LiveCred = Get-Credential`.
UsersFile	Required	The UsersFile parameter specifies the name and location of the `CSV_Parser.ps1` script. If you use a value that contains spaces, make sure that you enclose the whole value in double quotation marks.
EndRow	Optional	The EndRow parameter specifies the last data row of the CSV file to act upon. The default value is 1000000. If you don't specify a value, the script will act on all data rows in the CSV file until the end is reached. The header row that contains the column definitions isn't included in the count of data rows in the CSV file.
LogDirectory	Optional	The LogDirectory parameter specifies the location of the log files that are generated by the script. The name of a log file is CSV_Parser_<monthdateyear_time>.txt This file contains useful troubleshooting information. If you don't specify a value for LogDirectory, the log file is stored in the directory that is specified by the %TEMP% environment variable in your Windows profile. By default, the temporary directory is located at C:\Users\<username>\AppData\Local\Temp. If you specify a different log directory, make sure the specified directory exists, and make sure you have sufficient permissions to read and create files in that directory.
LogVerbose	Optional	The LogVerbose parameter enables detailed debug logging for advanced troubleshooting purposes. If you specify the LogVerbose parameter, detailed debug logging is enabled.
RemoteURL	Optional	The RemoteURL parameter specifies the URL that connects your local Windows PowerShell console to the remote cloud-based service. You don't have to use this parameter. The script will automatically connect to the correct datacenter. The only acceptable value for this parameter is `https://ps.outlook.com/powershell/`.
StartRow	Optional	The StartRow parameter specifies the beginning data row of the CSV file to act upon. The default value is 1. If you don't specify a value, the script will start on the first data row in the CSV. The header row that contains the column definitions isn’t included in the count of data rows in the CSV file.
ValidateAction	Optional	The ValidateAction parameter enables or disables validation. The default value is `$true`, which means all actions performed by the `CSV_Parser.ps1` script are validated. Validation requires several seconds per object. If you are certain the actions you are performing with the `CSV_Parser.ps1` script don't require validation, you can disable validation by setting the value to `$false`.
$WarningPreference	Not applicable	$WarningPreference controls the error handling for the script. You set the value for $WarningPreference by modifying the value in the `CSV_Parser.ps1` script. The possible values are `SlientlyContinue`, `Continue`, `Inquire`, `Suspend`, or `Stop`. SilentlyContinue If an error is encountered, the script continues without displaying the error. Continue If an error is encountered, the error is displayed and the script continues. Inquire If an error is encountered, the script pauses and you are forced to choose whether to continue, halt, or suspend the script. Stop If an error is encountered, the script stops. The default value is `SilentlyContinue`.

Top of page

How do you use the CSV_Parser.ps1 script?

Here's an example that shows how to use the CSV_Parser.ps1 script with the following details:

Path to CSV_Parser.ps1 script C:\Tools\CSV_Parser.ps1
CSV file name and path C:\Data\Bulk Import.csv

To use the CSV_Parser.ps1 script to import users that are defined in the "C:\Data\Bulk Import.csv" file

Click Start > All Programs > Accessories> Windows PowerShell > Windows PowerShell.
Run the following command:
Copy
$LiveCred = Get-Credential
In the Windows PowerShell Credential Request window that opens, type the Windows Live ID and password of an Exchange Online administrator account. When you're finished, click OK.

Run the following command:

Copy

C:\Tools\CSV_Parser.ps1 -LiveCredential $LiveCred -UsersFile "C:\Data\Bulk Import.csv"

Depending on the number of users and attributes that are defined in the CSV file, the script may take some time to run. Various messages and errors may be displayed. When the script is finished, you can view these messages in the log file named CSV_Parser_<monthdateyear_time>.txt. By default the log file is located at C:\Users\<user name>\AppData\Local\Temp\, but you can specify the log file location with the LogDirectory parameter.

Top of page

Troubleshoot the CSV_Parser.ps1 script

If you have difficulty running the script, or the script doesn't produce the results that you expected, try the following troubleshooting steps:

Verify that the structure and content of your CSV file is correct. To do this, refer to the test.csv file that is included with the CSV_Parser.ps1 script.
- The following attributes are always required: Action, Type, and Name.
- The EmailAddress attribute is required for Add and Update actions.
- The Password attribute is required for Add actions on mailbox users and mail users.
Make sure you are running the latest version of the script. The script has an automatic version check that runs every time you run the script. If you are using an outdated version of the script, you'll receive an error message similar to the following:
Error = This script version <version> is no longer supported. Please update to the latest version.
If the CSV_Parser.ps1 script has problems connecting to the cloud-based service, try connecting manually without using the script. For more information about how to connect Windows PowerShell to the cloud-based service, see Connect Windows PowerShell to the Service.
Check the log file. By default, the log files are located at C:\Users\<user name>\AppData\Local\Temp, but you can change the location with the LogDirectory parameter. The log files are named CSV_Parser_<monthdateyear_time>.txt.

Top of page

Unsupported attributes

The following attributes aren’t supported by the CSV_Parser.ps1 script:

ExtensionCustomAttribute1 – ExtensionCustomAttribute5

Top of page

Create and Configure Recipients with the CSV_Parser.ps1 script

Before you begin

Download the script

Options for the CSV file

Important attributes for the CSV file

Optional attributes for the CSV file

Options for the CSV_Parser.ps1 script

How do you use the CSV_Parser.ps1 script?

To use the CSV_Parser.ps1 script to import users that are defined in the "C:\Data\Bulk Import.csv" file

Troubleshoot the CSV_Parser.ps1 script

Unsupported attributes