In this post I'm going to try to rollup a number of different Contact Scripts I've posted over the past couple of years into one module that will hopefully make things a little easier to use when you want to do things with Contacts using EWS and Powershell
I've put the code for this script up in GitHub repo https://github.com/gscales/Powershell-Scripts/blob/master/EWSContacts/EWSContactFunctions.ps1 it's 1K+ lines and I hope to add a few more things to the script as I go (and fix bugs). But if anybody has idea's please use GitHub to submit them. You can download the script as a zip from here
So here's what it can do at the moment
Get-Contact
This can be used to get a Contact from the Mailbox's default contacts folder, other contacts sub folder or the Global Address List eg to get a contact from the default contact folder by searching using the Email Address (This will return a EWS Managed API Contact object).
Example 1
Get-Contact -MailboxName mailbox@domain.com -EmailAddress contact@email.com
This will search the default contacts folder using the ResolveName operation in EWS, it also caters for contacts that where added from the Global Address List in Outlook. When you add a contact from the GAL the email address that is stored in the Mailbox's contacts Folder uses the EX Address format. So in this case when you go to resolve or search on the SMTP address it won't find the contact that has been added from the GAL with this address. To cater for this the GAL is also searched for the EmailAddress you enter in (using ResolveName), if a GAL entry is returned (that has a matching EmailAddress) then the EX Address is obtained using Autodiscover and the UserDN property and then another Resolve is done against the Contacts Folder using the EX address.
Because ResolveName allows you to resolve against more then just the Email address I've added a -Partial Switch so you can also do partial match searches. Eg to return all the contacts that contain a particular word (note this could be across all the properties that are searched) you can use
Get-Contact -MailboxName mailbox@domain.com -EmailAddress glen -Partial
By default only the Primary Email of a contact is checked when you using ResolveName if you want it to search the multivalued Proxyaddressses property you need to use something like the following
Get-Contact -MailboxName mailbox@domain.com -EmailAddress smtp:info@domain.com -Partial
Or to search via the SIP address you can use
Get-Contact -MailboxName mailbox@domain.com -EmailAddress sip:info@domain.com -Partial
(using the Partial switch is required in this case because the EmailAddress your search on won't match the PrimaryAddress of the contact so in this case also you can get partial matches back).
There is also a -SearchGal switch for this cmdlet which means only the GAL is searched eg
Get-Contact -MailboxName mailbox@domain.com -EmailAddress gscales@domain.com -SearchGal
In this case the contact object returned will be read only (although you can save it into a contacts folder which I've used in another cmdlet).
Finally if your contacts aren't located in the default contacts folder you can use the folder parameter to enter in the path to folder that you want to search eg
Get-Contact -MailboxName mailbox@domain.com -EmailAddress gscales@domain.com -Folder "\Contacts\SubFolder"
Create-Contact
This can be used to create a contact, I've added parameters for all the most common properties you would set in a contact, some contact property need to be set via Extended properties (if you need to set this you can either add it in yourself or after you create the contact use Get-Contact and update the contact object).
Example 1 to create a contact in the default contacts folder
Create-Contact -Mailboxname mailbox@domain.com -EmailAddress contactEmai@domain.com -FirstName John -LastName Doe -DisplayName "John Doe"
to create a contact and add a contact picture
Create-Contact -Mailboxname mailbox@domain.com -EmailAddress contactEmai@domain.com -FirstName John -LastName Doe -DisplayName "John Doe" -photo 'c:\photo\Jdoe.jpg'
to create a contact in a user created subfolder
Create-Contact -Mailboxname mailbox@domain.com -EmailAddress contactEmai@domain.com -FirstName John -LastName Doe -DisplayName "John Doe" -Folder "\MyCustomContacts"
This cmdlet uses the EmailAddress as unique key so it wont let you create a contact with that email address if one already exists.
Update-Contact
This Cmdlet can be used to update an existing contact the Primary email address is used as a unique key so this is the one property you can't update. It will take the Partial switch like the other cmdlet but will always prompt before updating in this case.
Example1 update the phone number of an existing contact
Update-Contact -Mailboxname mailbox@domain.com -EmailAddress contactEmai@domain.com -MobilePhone 023213421
Example 2 update the phone number of a contact in a users subfolder
Update-Contact -Mailboxname mailbox@domain.com -EmailAddress contactEmai@domain.com -MobilePhone 023213421 -Folder "\MyCustomContacts"
Delete-Contact
This Cmdlet can be used to delete a contact from a contact folders
eg to delete a contact from the default contacts folder
Delete-Contact -MailboxName mailbox@domain.com -EmailAddress email@domain.com
to delete a contact from a non user subfolder
Delete-Contact -MailboxName mailbox@domain.com -EmailAddress email@domain.com -Folder \Contacts\Subfolder
Export-Contact
This cmdlet can be used to export a contact to a VCF file, this takes advantage of EWS ability to provide the contact as a VCF stream via the MimeContent property.
To export a Contact to a vcf use
Export-Contact -MailboxName mailbox@domain.com -EmailAddress address@domain.com -FileName c:\export\filename.vcf
If the file already exists it will handle creating a unique filename
To export from a contacts subfolder use
Export-Contact -MailboxName mailbox@domain.com -EmailAddress address@domain.com -FileName c:\export\filename.vcf -folder \contacts\subfolder
Export-GALContact
This cmdlet exports a Global Address List entry to a VCF file, unlike the Export-Contact cmdlet which can take advantage of the MimeStream provided by the Exchange Store with GAL Contact you don't have this available. The script creates aVCF file manually using the properties returned from ResolveName. By default the GAL photo is included with the file but I have included a -IncludePhoto switch which will use the GetUserPhoto operation which is only available on 2013 and greater.
Example 1 to save a GAL Entry to a vcf
Export-GalContact -MailboxName user@domain.com -EmailAddress email@domain.com -FileName c:\export\export.vcf
Example 2 to save a GAL Entry to vcf including the users photo
Export-GalContact -MailboxName user@domain.com -EmailAddress email@domain.com -FileName c:\export\export.vcf -IncludePhoto
Copy-Contacts.GalToMailbox
This Cmdlet copies a contact from the Global Address list to a local contacts folder. The EmailAddress in used as a unique key so the same contact won't be copied into a local contacts folder if it already exists. By default the GAL photo isn't included but I have included a -IncludePhoto switch which will use the GetUserPhoto operation which is only available on 2013 and greater.
Example 1 to Copy a Gal contacts to local Contacts folder
Copy-Contacts.GalToMailbox -MailboxName mailbox@domain.com -EmailAddress email@domain.com
Example 2 Copy a GAL contact to a Contacts subfolder
Copy-Contacts.GalToMailbox -MailboxName mailbox@domain.com -EmailAddress email@domain.com -Folder \Contacts\UnderContacts
I've put the code for this script up in GitHub repo https://github.com/gscales/Powershell-Scripts/blob/master/EWSContacts/EWSContactFunctions.ps1 it's 1K+ lines and I hope to add a few more things to the script as I go (and fix bugs). But if anybody has idea's please use GitHub to submit them. You can download the script as a zip from here
So here's what it can do at the moment
Get-Contact
This can be used to get a Contact from the Mailbox's default contacts folder, other contacts sub folder or the Global Address List eg to get a contact from the default contact folder by searching using the Email Address (This will return a EWS Managed API Contact object).
Example 1
Get-Contact -MailboxName mailbox@domain.com -EmailAddress contact@email.com
This will search the default contacts folder using the ResolveName operation in EWS, it also caters for contacts that where added from the Global Address List in Outlook. When you add a contact from the GAL the email address that is stored in the Mailbox's contacts Folder uses the EX Address format. So in this case when you go to resolve or search on the SMTP address it won't find the contact that has been added from the GAL with this address. To cater for this the GAL is also searched for the EmailAddress you enter in (using ResolveName), if a GAL entry is returned (that has a matching EmailAddress) then the EX Address is obtained using Autodiscover and the UserDN property and then another Resolve is done against the Contacts Folder using the EX address.
Because ResolveName allows you to resolve against more then just the Email address I've added a -Partial Switch so you can also do partial match searches. Eg to return all the contacts that contain a particular word (note this could be across all the properties that are searched) you can use
Get-Contact -MailboxName mailbox@domain.com -EmailAddress glen -Partial
By default only the Primary Email of a contact is checked when you using ResolveName if you want it to search the multivalued Proxyaddressses property you need to use something like the following
Get-Contact -MailboxName mailbox@domain.com -EmailAddress smtp:info@domain.com -Partial
Or to search via the SIP address you can use
Get-Contact -MailboxName mailbox@domain.com -EmailAddress sip:info@domain.com -Partial
(using the Partial switch is required in this case because the EmailAddress your search on won't match the PrimaryAddress of the contact so in this case also you can get partial matches back).
There is also a -SearchGal switch for this cmdlet which means only the GAL is searched eg
Get-Contact -MailboxName mailbox@domain.com -EmailAddress gscales@domain.com -SearchGal
In this case the contact object returned will be read only (although you can save it into a contacts folder which I've used in another cmdlet).
Finally if your contacts aren't located in the default contacts folder you can use the folder parameter to enter in the path to folder that you want to search eg
Get-Contact -MailboxName mailbox@domain.com -EmailAddress gscales@domain.com -Folder "\Contacts\SubFolder"
Create-Contact
This can be used to create a contact, I've added parameters for all the most common properties you would set in a contact, some contact property need to be set via Extended properties (if you need to set this you can either add it in yourself or after you create the contact use Get-Contact and update the contact object).
Example 1 to create a contact in the default contacts folder
Create-Contact -Mailboxname mailbox@domain.com -EmailAddress contactEmai@domain.com -FirstName John -LastName Doe -DisplayName "John Doe"
to create a contact and add a contact picture
Create-Contact -Mailboxname mailbox@domain.com -EmailAddress contactEmai@domain.com -FirstName John -LastName Doe -DisplayName "John Doe" -photo 'c:\photo\Jdoe.jpg'
to create a contact in a user created subfolder
Create-Contact -Mailboxname mailbox@domain.com -EmailAddress contactEmai@domain.com -FirstName John -LastName Doe -DisplayName "John Doe" -Folder "\MyCustomContacts"
This cmdlet uses the EmailAddress as unique key so it wont let you create a contact with that email address if one already exists.
Update-Contact
This Cmdlet can be used to update an existing contact the Primary email address is used as a unique key so this is the one property you can't update. It will take the Partial switch like the other cmdlet but will always prompt before updating in this case.
Example1 update the phone number of an existing contact
Update-Contact -Mailboxname mailbox@domain.com -EmailAddress contactEmai@domain.com -MobilePhone 023213421
Example 2 update the phone number of a contact in a users subfolder
Update-Contact -Mailboxname mailbox@domain.com -EmailAddress contactEmai@domain.com -MobilePhone 023213421 -Folder "\MyCustomContacts"
Delete-Contact
This Cmdlet can be used to delete a contact from a contact folders
eg to delete a contact from the default contacts folder
Delete-Contact -MailboxName mailbox@domain.com -EmailAddress email@domain.com
to delete a contact from a non user subfolder
Delete-Contact -MailboxName mailbox@domain.com -EmailAddress email@domain.com -Folder \Contacts\Subfolder
Export-Contact
This cmdlet can be used to export a contact to a VCF file, this takes advantage of EWS ability to provide the contact as a VCF stream via the MimeContent property.
To export a Contact to a vcf use
Export-Contact -MailboxName mailbox@domain.com -EmailAddress address@domain.com -FileName c:\export\filename.vcf
If the file already exists it will handle creating a unique filename
To export from a contacts subfolder use
Export-Contact -MailboxName mailbox@domain.com -EmailAddress address@domain.com -FileName c:\export\filename.vcf -folder \contacts\subfolder
Export-GALContact
This cmdlet exports a Global Address List entry to a VCF file, unlike the Export-Contact cmdlet which can take advantage of the MimeStream provided by the Exchange Store with GAL Contact you don't have this available. The script creates aVCF file manually using the properties returned from ResolveName. By default the GAL photo is included with the file but I have included a -IncludePhoto switch which will use the GetUserPhoto operation which is only available on 2013 and greater.
Example 1 to save a GAL Entry to a vcf
Export-GalContact -MailboxName user@domain.com -EmailAddress email@domain.com -FileName c:\export\export.vcf
Example 2 to save a GAL Entry to vcf including the users photo
Export-GalContact -MailboxName user@domain.com -EmailAddress email@domain.com -FileName c:\export\export.vcf -IncludePhoto
Copy-Contacts.GalToMailbox
This Cmdlet copies a contact from the Global Address list to a local contacts folder. The EmailAddress in used as a unique key so the same contact won't be copied into a local contacts folder if it already exists. By default the GAL photo isn't included but I have included a -IncludePhoto switch which will use the GetUserPhoto operation which is only available on 2013 and greater.
Example 1 to Copy a Gal contacts to local Contacts folder
Copy-Contacts.GalToMailbox -MailboxName mailbox@domain.com -EmailAddress email@domain.com
Example 2 Copy a GAL contact to a Contacts subfolder
Copy-Contacts.GalToMailbox -MailboxName mailbox@domain.com -EmailAddress email@domain.com -Folder \Contacts\UnderContacts