Manually Configuring Email Addresses for Exchange Server 2013 Recipients using PowerShell

This article is an excerpt from the upcoming Exchange Server 2013 PowerShell Guide

Managing email addresses for a mailbox is a good learning experience for dealing with multi-value attributes in PowerShell.

A mailbox can have multiple email addresses, for example where a company has rebranded and changed their primary email addresses to a new name, but still wish to keep receiving any emails sent to the old email addresses.

Another example is a person who has a name that is very long or easy to misspell. In these cases you can add a secondary address that is shorter or easier to spell to the mailbox.

Here is the current email address for my test mailbox. At the moment it has just one email address.

[PS] C:\>Get-Mailbox Paul.Cunningham | Select-Object EmailAddresses

EmailAddresses
--------------
{SMTP:paul.cunningham@exchange2013demo.com}

We’ve already looked at some examples of using Set-Mailbox to manage mailboxes. So you might go ahead and use it to add an email address to a mailbox like this.

[PS] C:\>Set-Mailbox Paul.Cunningham -EmailAddresses paulc@exchange2013demo.com

WARNING: Couldn't update the primary SMTP address because this mailbox is configured
to use an email address policy. To disable the email address policy for this mailbox,
run the command with the EmailAddressPolicyEnabled parameter set to $false.

The command fails because the mailbox has an email address policy applied to it. Following the suggestion in the warning message we can go ahead and disable the email address policy to be able to make the change to the mailbox.

[PS] C:\>Set-Mailbox Paul.Cunningham -EmailAddresses paulc@exchange2013demo.com -EmailAddressPolicyEnabled $false

This time no errors or warnings were returned. Let’s take a look at the result.

[PS] C:\>Get-Mailbox Paul.Cunningham | Select-Object EmailAddresses

EmailAddresses
--------------
{SMTP:paulc@exchange2013demo.com}

Whoops! Instead of adding an extra email address, the original email address has been overwritten. Let’s revert back to the original configuration and try again.

[PS] C:\>Set-Mailbox Paul.Cunningham -EmailAddresses paul.cunningham@exchange2013demo.com -EmailAddressPolicyEnabled $true

[PS] C:\>Get-Mailbox Paul.Cunningham | Select-Object EmailAddresses

EmailAddresses
--------------
{SMTP:paul.cunningham@exchange2013demo.com}

Now let’s explore this concept of multi-value attributes a little more. Here is a mailbox that already has multiple email addresses assigned to it.

[PS] C:\>Get-Mailbox Robert.Henderson | Select-Object EmailAddresses

EmailAddresses
--------------
{smtp:rob.henderson@exchange2013demo.com, SMTP:Robert.Henderson@exchange2013demo.com}

Using Get-Member we can see that the EmailAddresses attribute is a collection.

[PS] C:\>Get-Mailbox Robert.Henderson | Get-Member EmailAddresses

   TypeName: Microsoft.Exchange.Data.Directory.Management.Mailbox

Name           MemberType Definition
----           ---------- ----------
EmailAddresses Property   Microsoft.Exchange.Data.ProxyAddressCollection EmailAddresses

We can also expand the collection to see more details about each individual entry. Notice differences such as IsPrimaryAddress, and the ability to have a Prefix (i.e. for address types other than SMTP).

[PS] C:\>Get-Mailbox Robert.Henderson | Select-Object -ExpandProperty EmailAddresses

SmtpAddress        : rob.henderson@exchange2013demo.com
AddressString      : rob.henderson@exchange2013demo.com
ProxyAddressString : smtp:rob.henderson@exchange2013demo.com
Prefix             : SMTP
IsPrimaryAddress   : False
PrefixString       : smtp

SmtpAddress        : Robert.Henderson@exchange2013demo.com
AddressString      : Robert.Henderson@exchange2013demo.com
ProxyAddressString : SMTP:Robert.Henderson@exchange2013demo.com
Prefix             : SMTP
IsPrimaryAddress   : True
PrefixString       : SMTP

When we used Set-Mailbox in the earlier example it overwrote the existing attribute with the new value, rather than insert or append the new value to the existing one.

To get the desired result we need to use different syntax. Don’t worry, it isn’t difficult at all.

[PS] C:\>Set-Mailbox Paul.Cunningham -EmailAddresses @{Add='paulc@exchange2013demo.com'}

It’s as simple as that. Here is the result. The email address policy is still applying the primary email address of paul.cunningham@exchange2013demo.com, but the shorter address of paulc@exchange2013demo.com has been added as well.

[PS] C:\>Get-Mailbox Paul.Cunningham | Select-Object -ExpandProperty EmailAddresses

SmtpAddress        : paulc@exchange2013demo.com
AddressString      : paulc@exchange2013demo.com
ProxyAddressString : smtp:paulc@exchange2013demo.com
Prefix             : SMTP
IsPrimaryAddress   : False
PrefixString       : smtp

SmtpAddress        : paul.cunningham@exchange2013demo.com
AddressString      : paul.cunningham@exchange2013demo.com
ProxyAddressString : SMTP:paul.cunningham@exchange2013demo.com
Prefix             : SMTP
IsPrimaryAddress   : True
PrefixString       : SMTP

Want to remove an address instead? Just as easy.

[PS] C:\>Set-Mailbox Paul.Cunningham -EmailAddresses @{Remove='paulc@exchange2013demo.com'}

In the example above the primary email address for the mailbox has remained the same and additional email addresses have been added or removed.

If you need to change the primary email address for the mailbox instead, then there is a slightly different approach used.

First you need to disable email address policies for the mailbox. Don’t worry; this does not remove any of the email addresses that the policy has already added.

[PS] C:\>Set-Mailbox Paul.Cunningham -EmailAddressPolicyEnabled $false

Next we need to use Set-Mailbox and provide the entire set of email addresses that we want to exist on the mailbox, using the case-sensitive prefix “SMTP” to specifiy which one is the primary address.

[PS] C:\>Set-Mailbox Paul.Cunningham -EmailAddresses SMTP:paulc@exchange2013demo.com,smtp:paul.cunningham@exchange2013demo.com

Let’s take one last look at the results.

[PS] C:\>Get-Mailbox Paul.Cunningham | Select-Object -ExpandProperty EmailAddresses

SmtpAddress        : paul.cunningham@exchange2013demo.com
AddressString      : paul.cunningham@exchange2013demo.com
ProxyAddressString : smtp:paul.cunningham@exchange2013demo.com
Prefix             : SMTP
IsPrimaryAddress   : False
PrefixString       : smtp

SmtpAddress        : paulc@exchange2013demo.com
AddressString      : paulc@exchange2013demo.com
ProxyAddressString : SMTP:paulc@exchange2013demo.com
Prefix             : SMTP
IsPrimaryAddress   : True
PrefixString       : SMTP

As you can see the paulc@exchange2013demo.com email address was added to the mailbox and was made the primary email address as well.