Enter Search Query:

Bulk-create external email contacts in Exchange/Office 365

Say someone asked you to create an exchange distribution group with a thousand new external email addresses. Well, back in the day, you’d download some shady utility off the web and cross your fingers hoping not to spend the rest of your day cleaning up a failed bulk import with ADSIedit. Well, with Exchange 2007 and up/office365, you can use powershell to do this. Here’s how:

[the problem]

Need to batch/bulk create a lot of exchange/active directory contacts with external SMTP addresses.


Powershell with exchange commandlets


[step 1] Create a CSV file that contains the information about your external contacts. A lot of information is great if that’s how you want your contacts. Powershell will allow you to import lots of information about each contact from a CSV file. Here’s a sample of a csv file from Microsoft. We’ll call this Sample_A:


I like my external contacts pretty bare. Just an email address and a name…or even just an email address. Also, note that the New-MailContact command will concatenate the first and last name to create the exchange alias automatically unless you specify that. I don’t like this because in a large organization it’s hard enough to deal with unique aliases for people that have the same names. I don’t need to throw a thousand external contacts with similar names into mix making my exchange alias problem even worse. I typically will modify my CSV file so it just shows two columns: 1. ExternalEmailAddress, 2.Alias. The Alias is just the email address with the @ symbol and the period removed.

Here’s how I typically format my external contact CSV import file. We’ll call this Sample_B:


[step 2] Create an organizational unit for your new contacts. To the end user there’s no difference, but this will allow you to manage them as one entity. Say you just import them to the default container, well if you’ve already got contacts there, you’ll have to sort through a big pile of crap if someone asks you to delete just those contacts you last imported.

[step 3A] If you like your contacts with lots of information (sample_A.csv), open a powershell command and change directory (CD) to the folder containing your CSV file. Then run the following command:

Import-Csv .sample_A.csv|%{New-MailContact -Name $_.Name -DisplayName $_.Name -ExternalEmailAddress $_.ExternalEmailAddress -FirstName $_.FirstName -LastName $_.LastName -OrganizationalUnit "My Imported Contacts"}

This will create the contacts with some information. Now that they’re created, you’d run the following command to populate each contact with all the other data in your CSV file:

$contacts = Import-CSV .sample_A.csv
$contacts | ForEach {Set-Contact $_.Name -StreetAddress $_.StreetAddress -City $_.City -StateorProvince $_.StateorProvince -PostalCode $_.PostalCode -Phone $_.Phone -MobilePhone $_.MobilePhone -Pager $_.Pager -HomePhone $_.HomePhone -Company $_.Company -Title $_.Title -OtherTelephone $_.OtherTelephone -Department $_.Department -Fax $_.Fax -Initials $_.Initials -Notes $_.Notes -Office $_.Office -Manager $_.Manager}

[step 3B] If you prefer your contacts to look like sample_B where they’ll just have the email address as the name and the alias as the exchange alias, then run the following command:
Import-Csv .sample_B.csv|%{New-MailContact -Name $_.ExternalEmailAddress -Alias $_.Alias -ExternalEmailAddress $_.ExternalEmailAddress -OrganizationalUnit "My Imported Contacts"}
That’s really all there is to it.


[download] sample_A.csv

[download] sample_B.csv

[howto] Open a powershell session to Office365


May 15, 2014

Related Posts

13 comments found

Comments for: Bulk-create external email contacts in Exchange/Office 365

  1. David Cunningham

    How do I add these newly created contacts to a public folder contacts list called SaleContatcs? When I am in Outlook GAL I only see them under Address book – All contacts

  2. David Cunningham

    How do I add these newly created contacts to a public folder contacts list called Sales Contacts? When I am in Outlook GAL I only see them under Address book – All contacts int he address book

    1. Post author: 
      David Vielmetter

      Hi David,

      Ok, just a quick note first, I believe any “mail-enabled” contact will show up in the GAL regardless of whether or not it is stored in a public folder. Depending on how you created them, the easiest way to move contacts to a public folder would probably within outlook. I’d select a user who has access to the public contacts folder you want to add the contact so and open Outlook for that user. Make sure the user has an empty root contacts folder (you can do this by moving all existing contacts for that user to a new folder or a subfolder temporarily. then go to the address book and select all your mail enabled contacts and select “add to contacts”. this will add them to that users contacts folder and from there you can copy them to the public folder.

      Then if desired, on individual instances of Outlook, you can right click the public folder and select the option to list the contacts in the public folder in the address book…but this is not required since mail enabled contacts will already be in the GAL.

      Hope it helps,

      1. Post author: 
        David Vielmetter

        oh, and if you’re having trouble sorting the address book to isolate all the contacts you created, you may want to revisit your batch contact creation script and modify the batch so that all the contacts you created have a unique identifier you can sort the address book by like “location”.


  3. David Cunningham

    I did manually add all the GAL to my contacts and them moved those contacts I needed to the public folder contact list. I just wish there was a better way then all these steps to get Public contacts.

  4. villy Feltmann

    When I run the first part (3A) with -OrganizationalUnit “My Imported Contacts” i got the error: Organizational unit “My Imported Contacts” was not found. Please make sure you have typed it correctly.
    which I asume must be set before the script is run, but how do i set the Organizational unit? i have no internal server only pure 365 business pemium and a E3 for a client. and I’m a rookie in powershell and office 365 so I preciate pages like yours.

    1. David Vielmetter

      Open Active Directory Users and Computers (ADUC) and at the top of the root (Domain) select new->Organization Unit (OU) and give it the name you want.


  5. Tausif

    What if i have more than 1 email per user and have to set 1 email external from them, any help highly appreciated…

    1. David Vielmetter

      Well, ok so this article talks about adding contacts not users. That said, you can certainly add multiple email addresses to each contact using standard concatenation +=. Theoretically there’s no limit on how many smtp addresses you can add to a contact as they’re unique. Maybe something like
      Import-Csv data.csv | Foreach-Object{
      $contact = Get-MailContact -Identity $_.name
      $contact.EmailAddresses+=$_.SecondayAddress (you could add more here based on how many columns you have)
      Set-MailContact $contact -EmailAddresses $contact.EmailAddresses

      1. Tausif

        Thanks David!!

  6. Mike

    I keep getting the error “The term ‘New-MailContact’ is not recognized as the name of a cmdlet, function, script…”

    Any ideas on why that is?

    1. Mike

      Found it, I needed to log in in a different way. I used MSOL-Connect instead of the Import Session method.

  7. charles

    David thanks for this write up…
    I am trying to run the second part of the script as I have already added the Contacts and I am just trying to add their phone info but I keep receiving a prompt
    Supply values for the following parameters:
    what am I doing wrong?

Leave a Reply

Your email address will not be published. Required fields are marked *