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.
[requirements]
Powershell with exchange commandlets
[solution]
[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.
References:
[download] sample_A.csv
[download] sample_B.csv
[howto] Open a powershell session to Office365
Comments
15 responses to “Bulk-create external email contacts in Exchange/Office 365”
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
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
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,
David
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”.
Cheers,
David
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.
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.
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.
Cheers,
David
What if i have more than 1 email per user and have to set 1 email external from them, any help highly appreciated…
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
}
Thanks David!!
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?
Found it, I needed to log in in a different way. I used MSOL-Connect instead of the Import Session method.
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:
Identity:
what am I doing wrong?
Thanks
I am looking to export contacts from an accounting program to email out PDF EFT Notifications to the contact that I would like to have in a DG called EFT_Clients… I have searched for several days on how to do so and NO luck at all… Each cheque/eft run I would like the accounting program to take all email addresses inside the file, export them to a csv file and be able to import those to the DG I created.. I also need it to send the individuals their own notification, not a bulk one…
I CAN get the PDF Notification and email address to a file, but cannot seem to tie it into an Exchange DG where a bulk email isn’t going out… Please any help!
Well, either your create a Distribution List (DL) with a bunch of contacts in it in exchange and then use it as a simple way to send emails to lots of contacts or you do a mail merge. It’s unclear to me from your question which you’re trying to do.
If you want to simply use one “contact” to send an email to multiple people, then you’d have to create a Distribution List (DL) in office365 first. Once you have your DL created, then the next step would be to add any contacts to it. Then once your DL is created and has all contacts as part of it, then when users send an email to that DL, it’ll hit all the individuals that are members of the DL.
If you wanted to do a mail merge, then you could certainly use a csv file with email addresses as the source of your email addresses. There’s lots of tutorials on how to create a mail merge in Outlook to send an email to a number of emails in a csv file. That process utilizes Microsoft Word and Microsoft Outlook and has nothing to do with exchange or office365.
hope it helps,
David