Create and Configure Recipients with the CSV

Create and Configure Recipients with the CSV_Parser.ps1 script

Download and use the CSV_Parser.ps1 Windows PowerShell script to add new users, update existing users, or delete existing users in Outlook Live. 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 Web management interface. For more information, see Import New Users with a CSV File.

Use the script for the following user types:

Mailbox users Mailbox users are users in your Outlook Live 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 Outlook Live, 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 Outlook Live, 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
Options for the CSV_Parser.ps1 script
How do you use the CSV_Parser.ps1 script?
Troubleshoot errors from the CSV_Parser.ps1 script

Before you begin

To learn how to install and configure Windows PowerShell and connect to Outlook Live, see Use Windows PowerShell.

You don't have to connect Windows PowerShell to Outlook Live before you run the script. The script connects to Outlook Live 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 Outlook Live 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.

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

This table lists all the supported attributes.

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. 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. When you delete a mailbox user, the mailbox is deleted, and the corresponding Windows Live ID is put into a forced rename state. For more information about the forced rename state, see Import or Evict Existing Windows Live IDs. 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 Outlook Live organization. Use MailContact for users that are outside your domain. 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 Outlook Live organization. Use MailUser for members of your organization who don't have an Outlook Live mailbox. For example, use MailUser for the faculty and staff of a university where only the students and alumni have Outlook Live mailboxes.
Name	Always required	Name specifies an identifier for the user. When you create new mailbox 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. You can't modify the value of the Name attribute on an existing user. The Name attribute is important for Windows PowerShell operations on Outlook Live 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 Outlook Live address book. Note Make sure the value that you use for Name is unique in your Outlook Live organization. If you create two accounts with the same value of Name but different Windows Live IDs, Outlook Live will have 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 Web management interface. 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.
EmailAddress	Required for Add and Update actions Not used with Delete actions	EmailAddress specifies the e-mail address of a new user. When you create new mailbox users, the EmailAddress attribute is used as the e-mail address for the mailbox and is used to create the corresponding Windows Live ID. The value of EmailAddress must be unique in the Outlook Live organization. For mailbox users and mail users, the value of EmailAddress must be in an accepted domain of the Outlook Live organization. For mail contacts, the value of EmailAddress can't be in an accepted domain of the Outlook Live organization. You can't update the e-mail address for an existing user. For more information about accepted domains, see Accepted Domains.
FirstName	Required for Add actions on mailbox users Optional for Add or Update actions on mail contacts or mail users 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, the value of FirstName is also used as the first name of the Windows Live ID.
KeepWindowsLiveID	Optional for Delete actions on mailboxes. Not used with Add or Update actions	KeepWindowsLiveID is only available when you delete mailboxes. When set to `Y`, the Windows Live ID that is associated with the deleted mailbox is retained. If the KeepWindowsLiveID attribute isn't defined in the header row, or if the value of KeepWindowsLiveID isn't Y, the Windows Live ID of the removed mailbox is deleted.
LastName	Required for Add actions on mailbox users Optional for Add or Update options on mail contacts or mail users 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, the value of LastName as also used as the last name of the Windows Live ID.
MailboxPlan	Optional for Add actions on mailbox users Not used with Update or Delete actions	MailboxPlan is only available 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 for Outlook Live.
Password	Required for Add actions on mailbox users Optional for Update actions on mailbox users Not used with Delete actions	Password is the Windows Live ID password for a mailbox user. The Password attribute is required when you create new mailbox users and can be used optionally to reset an existing mailbox user's password. The Password attribute doesn't apply to mail contacts or mail users. To force a mailbox user to change their password after they log on, use the ForceChangePassword attribute. For more information about passwords, see Password Guidelines for Outlook Live.
City	Always optional Not used with Delete actions	City specifies the city that is listed for the user in the address book. If you don’t supply this information, the City field is left blank.
Company	Always optional Not used with Delete actions	Company specifies the company name that is listed for the user in the address book. If you don’t supply this information, the Company field is left blank.
CountryorRegion	Always optional Not used with Delete actions	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 Web management interface for Outlook Live.
CustomAttributeN where N is an integer from 1 through 15.	Always optional Not used with Delete actions	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 Web management interface 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	Always optional Not used with Delete actions	Department specifies the department that is listed for the user in the address book. If you don’t supply this information, the Department field is left blank.
EmailAddressN where N is an integer from 2 through 5.	Always optional 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 Outlook Live organization. For mail contacts, the proxy address can't be in an accepted domain of the Outlook Live organization. For more information about accepted domains, see Accepted Domains.
Fax	Always optional Not used with Delete actions	Fax specifies the fax number that is listed for the user in the address book. If you don’t supply this information, the Fax field is left blank.
ForceChangePassword	Optional for Add actions on mailbox users Not used with Update or Delete actions	ForceChangePassword is available only when you are creating new mailbox users. When ForceChangePassword is set to `1`, or if the ForceChangePassword attribute isn't defined in the header row, ForceChangePassword creates a Windows Live ID that requires new users to 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.
HomePhone	Always optional Not used with Delete actions	HomePhone specifies the home phone number that is listed for the user in the address book. If you don’t supply this information, the Home phone field is left blank.
Initials	Always optional Not used with Delete actions	Initials specifies the middle initial that is listed for the user in the address book. If you don’t supply this information, the Initial field is left blank.
MobilePhone	Always optional Not used with Delete actions	MobilePhone specifies the mobile phone number that is listed for the user in the address book. If you don’t supply this information, the Mobile phone field is left blank.
Notes	Always optional Not used with Delete actions	The Notes field specifies additional information that is listed for the user in the address book. If you don't provide any information, the Notes field is left blank.
Office	Always optional Not used with Delete actions	Office specifies the office location that is listed for the user in the address book. If you don’t supply this information, the Office field is left blank.
Phone	Always optional Not used with Delete actions	Phone specifies the work phone number that is listed for the user in the address book. If you don’t supply this information, the Work phone field is left blank.
PostalCode	Always optional Not used with Delete actions	PostalCode specifies the postal code that is listed for the user in the address book. If you don’t supply this information, the Zip / Postal code field is left blank.
StateorProvince	Always optional Not used with Delete actions	StateorProvince specifies the state or province that is listed for the user in the address book. If you don’t supply this information, the State / Province field is left blank.
StreetAddress	Always optional Not used with Delete actions	StreetAddress specifies the street address that is listed for the user in the address book. If you don’t supply this information, the Street field is left blank.
Title	Always optional Not used with Delete actions	Title specifies the title that is listed for the user in address book. If you don’t supply this information, the Title field is left blank.
WebPage	Always optional Not used with Delete actions	WebPage specifies the Web page address that is listed for the user in the address book. If you don’t supply this information, the Web page field is left blank.

Options for the CSV_Parser.ps1 script

Parameter	Required	Description
LiveCredential	Required	The LiveCredential parameter specifies the Windows Live ID and password of an Outlook Live administrator account in your Outlook Live 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 Outlook Live 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`.

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:
```
$LiveCred = Get-Credential
```
In the Windows PowerShell Credential Request window that opens, type the Windows Live ID and password of an Outlook Live administrator account. When you're finished, click OK.

Run the following command:

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.

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, Name.
- The EmailAddress attribute is required for Add and Update actions.
- The Password attribute is required for Add actions on mailbox 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 Outlook Live, try connecting to Outlook Live manually without using the script. For more information about how to connect Windows PowerShell to Outlook Live with Windows Remote Management (WinRM), see Connect Windows PowerShell to Outlook Live.
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.