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.

About the Author

Paul Cunningham

Paul is a former Microsoft MVP for Office Apps and Services. He works as a consultant, writer, and trainer specializing in Office 365 and Exchange Server. Paul no longer writes for Practical365.com.

Comments

  1. Sri

    Hi Paul, I am a big fan of yours. I require a help with the script to capture all the x500 proxy addresses of mail contacts from a specific OU and then write it back to the mail contacts on a different OU.

  2. Barnster

    Hi Paul
    Really like the format you have used and the explanations along the way.
    Hoping you can help me with a very similar issue to what you have presented.
    What I am trying to do is very similar but with one big difference, I’m trying to add an additional email address to a Mail Enabled AD Security Group (DistributionGroup). What I need to do is as follows –

    1. add additional email address to mail enabled Security Group (eg. ???@abcd.net.co)
    2. disable the ’email address policy’
    3. make the new email address the primary SMTP address (change primary SMTP from ???@xyz.com.au to ???@abcd.net.co)

    Would really appreciate any assistance you can provide.

  3. Kristy

    Thank you!! This was exactly what I needed.
    [PS] C:\>Set-Mailbox Paul.Cunningham -EmailAddresses SMTP:paulc@exchange2013demo.com,smtp:paul.cunningham@exchange2013demo.com

  4. Dee

    Hi,

    I am very new to scripting.
    I would like to add “zzz” to existing SMTP and smtp addresses of usernames in a CSV file. Anyone has script for this?

    Thanks in advance!

      1. Dee

        Thank you so much Paul! Sorry for the very delayed reply. I’ll check the script.

  5. Christian

    how can i change the setting for users of a special OU ?

    found this, but is not working in exchange 2016:
    Get-mailbox -OrganizationalUnit “OU name”| set-mailbox EmailAddressPolicyEnabled $true
    Argument true is not acceptet

    1. Paul Cunningham

      You’re missing the hyphen on the -EmailAddressPolicyEnabled parameter.

      1. Christian

        thx!

        Sometimes its so easy that you dont see it yourself 😉

  6. Vik

    what would be the command to do a bulk Primary SMTP change while data is imported a file .

      1. Jim

        Hi Paul
        I am in this situation – after some acquisitions we are standardizing on one @domain and want to do a first.last but the givenName is controlled by HR and isn’t always suitable for the addresses. I could populate an extensionAttribute with the desired prefix, like “preferred-first.initial.last” but don’t know how to specify that as the email address format.
        Is it even possible?
        Thanks for all the years of help this site has provided!
        Jim

  7. Roger

    Paul,

    This is a great article. I am wondering how I can use this to modify the existing EUM addresses that are on a users mailbox. Sometimes we have the need to modify the extension and other times the EUM address that matches their primary SMTP. Below are examples of what I am trying to change. I cannot figure out how to identify the EUM address that contains the extension and modify it without adding another extension attribute.

    EumAddress : 22222;phone-context=Default_UM.domain.com
    AddressString : 22222;phone-context=Default_UM.domain.com
    ProxyAddressString : eum:22222;phone-context=Default_UM.domain.com
    Prefix : EUM
    IsPrimaryAddress : False
    PrefixString : eum

    EumAddress : LYNHO01D@email.com;phone-context=Default_UM.domain.com
    AddressString : LYNHO01D@email.com;phone-context=Default_UM.domain.com
    ProxyAddressString : EUM:LYNHO01D@email.com;phone-context=Default_UM.domain.com
    Prefix : EUM
    IsPrimaryAddress : True
    PrefixString : EUM

  8. arika

    i like it

  9. Fernando

    Hi Paul. This post is very useful however I’m a little confused about -EmailAddresses parameter.
    I’ve seen this parameter for Set-Mailbox as well as for Set-MailUser and I don’t understand the differences.
    Some internet post says Set-Mailbox is for Exchange On-Premises and Set-MailUser is for Office 365 but at Microsoft web site doesn’t seem to be so clear about it.

    I’ll appreciate your comments.

    Thanks a lot!

    1. Paul Cunningham

      Mailboxes and mail users are two different recipient types. You can read about all the different recipient types here:

      https://technet.microsoft.com/en-us/library/bb201680%28v=exchg.150%29.aspx?f=255&MSPPError=-2147217396

      Basically, Set-Mailbox would be used for a Mailbox User, which is an Active Directory user that has a mailbox in the Exchange organization. This is the most common type of recipient.

      Set-MailUser would be used for a Mail User, one example of which is an Active Directory user who has a mailbox hosted in Office 365. Set-MailUser makes changes to the attributes in your Active Directory which will then synchronize with Office 365 via your directory synchronization (if you’ve deployed it in your particular scenario).

      Edit: not to be confused with an Office 365 mailbox user, which is for Hybrid scenarios. See the link above for details.

      1. Fernando

        Thanks a lot Paul. Very helpful!

  10. tarun

    i have added secondary email address but when i sent the test mail to secondary email address, i have received that email that’s fine, but if some one will send an email to anyone though it is secondary or primary how we can verify who has received an email? primary or secondary.

    Thanks

  11. Melwin Jerome

    Dear Paul,

    I am trying to modify all -Emailaddress of the single user like if he have 2 mail-ids like dave@corp.com,
    dave1@corp.com
    i want to update like Disabled_dave@corp.com,Disabled_dave1@corp.com. I am using the following code but it is not doing that job, Please guide me.

    $UD = Get-Mailbox -Identity $_identity
    $SmtpAdd=$null
    $Changed = $null
    $SmtpAdd=$UD|select -ExpandProperty EmailAddresses|Select SmtpAddress
    foreach($address in $SmtpAdd)
    {
    $result= $address.SmtpAddress
    $Changed += “SMTP:Disabled_”+$address.SmtpAddress.ToString()
    }
    $Changed1 = $Changed -join ‘,’
    Set-Mailbox $_identity -EmailAddresses $Changed1 -EmailAddressPolicyEnabled $true

  12. Phil Ready

    Hi Paul
    How can I make a new EmailAdressPolicy default? I see I cannot delete the old policy until I make the new one default, but cannot find the command.

    Thanks

    1. Paul Cunningham

      When multiple email address policies exist the policy that “wins” is the one that has a filter that matches the recipient in question. If multiple policies match then the highest priority policy wins.

      The Default Policy has a priority of “Lowest” and is designed to catch all recipients that other policies do not match.

  13. Mohammad

    Can’t we use set-mailbox user -primarysmtpaddress user@domain.com?
    Even in case of multivalue?

  14. Vik

    I have a user who is on office 365 and i need change her alias proxy address. At first the alias to logon to the webmail for 365 emails was different so now i need to change the alias and email address will remain the same. Is there a script i se for that i am not sure if this is correct.

    Set-Mailbox -Identity $Alias -EmailAddresses @{add=’smtp:xxxxx@yurowndomain.com’

  15. Angelos

    hi guys
    great article as always – but I have the same issue about putting proxy addresses on CONTACTS .

    before in 2010 I was able to set ANY email address as proxy address/alias to the email address. Now in 2013 I can only put INTERNAL emails domain, so that goes out… (at least from the ECP)

    would the same / similar commands run on the contact?

    the thing is when a contact has changed an email address, we usually keep the old on in for a while to avoid people sending to the “wrong” – old email address, as then exchange would reroute this email to the “PRIMARY EXTERNAL EMAIL ADDRESS”. But now in 2013 you are only able to add internal addresses, in which case you cannot do this any more.

    thanks
    Angelos

    1. Paul Cunningham

      If people are picking the contact from your GAL or their auto-complete cache I don’t see how keeping the old address associated with the contact helps.

      At any rate, what you’re seeing is how I’d expect it to behave, so there’s no other way to do it that I’m aware of.

      1. angelos

        It does help as the exchange will only send to the contact on its external email address. So if they send to one of the proxy addresses the exchange will automatically reroute it to the external email address. That way if someone used the old address by mistake it will still go to the correct one. Tried and tested 100% 🙂

        So the question is still if there is a way to see and modify the proxy addresses on a contact via command line. Unfortunately the mailbox proxy command arguments don’t work on the contacts…

  16. AJ

    Just a quick one. What’s the command to see which users don’t have any email policy applied to them?

  17. abdullah

    hello Paul
    which permission does the user need to change email address ?
    i need the specified permission

    thanks

  18. Glenn

    Hi Paul,
    I am trying to add secondary smtp addresses to remote cloud mailboxes using import-csv.

    When I try using this , to have it read from each line the of csv’s proxyaddresses column, it fails as it appears to see the “$_.proxyaddresses” as an invalid smtp address and not read and use the correct addresses from the file.

    Any thought I what I am missing?

    Thanks

    1. Glenn

      Sorry , seems to have dropped this when I posted.

      This is what I am using that does not read from the csv file
      -EmailAddresses @{add=”$._proxyaddresses”}

  19. JP O Leary

    Hi Paul,

    The article above is very good.

    What powershell script would I use to delete a specific smtp address from all users in a domain?

    For example I want to delete all smtp address ending in source.local or target.local.

    Thanks

    JP

  20. Carl Frank

    Paul,

    Great Stuff!

    Question: We just migrated 450 mailboxes from on prem exchange 2010 to O365 Enterprise and, in the cloud the mailbox email addresses have all applied the UPN as the SIP address. This is breaking the functionality between Outlook and Lync as the Default SMTP addresses in most cases are not the same as the UPN.

    I tested by adding SIP addresses to the proxy attribute for a few accounts on premises and after running dirsync, they are now correct in the cloud. Currently there are no SIP addresses on premises, so I am trying to identify a way to create a SIP address that mirrors the default SMTP address in bulk on the Exchange 2010 side.
    Any thoughts would be appreciated. I aqm getting up to speed on Powershell, but still quite a novice.
    Thanks,

    1. Steve Rackham

      Hi Carl
      Did you ever find out how to do this?
      I have a similar scenario where I want to add the SIP address based on primary SMTP address.
      Thanks for your help.

      S.

      1. Steve Rackham

        Hi All
        I muddled my way through and came up with the following which worked beautifully.

        ForEach ($mbx in $mbxes) {
        # SET THE newSIP ADDRESS VARIABLE TO MATCH THE PRIMARY SMTP ADDRESS:
        $newSIP = ‘SIP:’ + $($mbx.PrimarySmtpAddress)
        Write-Host “Adding $newSip to” $mbx.SamAccountName

        # ADD THE newSIP ADDRESS TO THE MAILBOX:
        Set-Mailbox -Identity $mbx.SamAccountName -EmailAddresses @{Add = $newSip}
        }

  21. Lars Panzerbjørn

    Thanks for the article 🙂

    I am trying to add an email address and make it the Primary SMTP Address, but without having to copy out all the other addresses first, but I can’t really figure out how to do it.

    I tried:
    Set-Mailbox -Identity $Alias -EmailAddresses @{add=’smtp:panzer@bjrn.com’}

    But that doesn’t seem to do the trick. It just adds the address.

    Is what I’d like to do even possible?

    1. Paul Cunningham

      Read the part of the article that starts with “If you need to change the primary email address for the mailbox instead, then there is a slightly different approach used.”

  22. Hans Peeters

    Hello,

    We need to change primary email address for most of our 2500 mailboxes. For specific reasons we connot use Email Address Policies, we need to use powershell.
    At the end of this article we have found the powershell command.
    All working fine in lab.
    However we noticed that other types of addresses like SIP and X400 disappear.

    How can we change primary smtp address by keeping SIP and X400 address of mailbox?

    Regards
    Hans

    1. Paul Cunningham

      I just test the “add” method demonstrated in the article and it didn’t remove the SIP address on the mailbox.

  23. MHD

    Hello dear,
    I have a question about Ms -Exchange 2013, hope you can help me about that.
    i have a distribution group named “support”, toe people (sam, mike) are member of group.
    they both receive any email had sent to this group.
    it is important that all their outgoing email send by support account ,not their own account.
    they only solution that i khnow is using “send As permission” but we are not sure they do this every time that they want send email.
    is there any other reliable solution for that?
    i really really appreciative your time and help.
    Thank you in advance.
    MHD

  24. Rene

    Hello,

    I have several users with multiple e-mail addressen, I would like to change there primary addresses but when i set a new default email adresses the other addresses are deleted.
    I only need to change the Isprimary flag but I can’t it tells me that it’s readonly

    Is there a simple way of doing this ?

  25. Courtney

    Wait, Could I just do the following?
    get-mailbox -resultsize unlimited |Set-Mailbox -EmailAddresses @{Remove=’*@old.emaildomain.com’}

    Thanks!

    1. Courtney

      No That doesn’t work. Can you help?

  26. Courtney

    Hi Paul,

    We used to be on Exchange 2003 where Recipient Policies controlled the Email address policy. Many of our older mailboxes have multiple email addresses that I need to remove. I can search the EmailAddresses multi-value field for the mailboxes that have that email domain that we don’t use, but I don’t know how to remove them. Since the Recipient Policy created them all, they are all created with the following format “alias@old.emaildomain.com”. How would I script it using a variable for alias? Sorry, I’m doing great with CMDLETs but haven’t scripted much.

    Thanks so much!

  27. Saul Nolasco

    Paul,

    Hopefully you are still reading this comment thread. Is there a way to set that parameter to false at a global level? Doing it for all of the mailboxes, This has been causing issues for some of my users and I have +500 to take care of. Doing one by one can get a bit tedious.

    Thanks

    1. Saul Nolasco

      Nevermind, I did not see the comment that Petemoss posted.

      Thanks

  28. Petemoss007

    I’ll look at the script. I’d prefer to use an email policy but since I cannot specify applying it to only the people with a specific domain name in their primary email address, I will probably have to use the script somehow.

  29. Petemoss007

    My issue is that these users are in multiple OU’s, multiple departments, etc. If I could setup a new policy and have a custom attribute that says “if the users primary email ends in @companA.com” then it would work. But I have to find all the users in all the OU’s with a primary email address ending in @companyA.com and add a new email address and make it primary.

    When I looked at custom attributes I did not see where I could specify anything like the above.

    Also, thank you so much for trying to help me with this.

    1. Paul Cunningham

      Read the article I linked to above, particularly the PowerShell example towards the end. You can use -RecipientFilter to be as broad or as specific as you need to.

      If you’d rather just write a script that’s fine, I’m just suggesting email address policies may be another solution for you.

  30. Petemoss007

    I have the exact scenario you mentioned at the beginning. A company with many users all with more than one email address. The company is rebranding from CompanyA to CompanyB. So I need a powershell command to check all users and, if they have an email ending in @companyA.com that is set to the primary, I need to add that user an email address ending in @companyB.com and make it the primary while leaving all the existing email addresses in place.

  31. Anant

    Hi,

    I am using

    get-mailbox abc@domain.com,xyz@domain.com

    get-mailbox abc@domain.com;xyz@domain.com

    get-mailbox -identity abc@domain.com,xyz@domain.com

    nothing is working. I want output of specific mailboxes.

    Please suggest.

    Thanks

  32. itworkedinthelab

    always great stuff
    Thanks

  33. Tunde

    Thanks, Paul. I feel really silly reading this article because I thought, Ohh…I know how to do all this, then I saw that simple @{Add=”SmtpAddress’}. I never knew I could objects to arrays like that. Here is the same of how I’ve been doing similar thing.
    ———————
    $OwnerMailbox = Get-Mailbox $Owner
    $UserMailbox = Get-Mailbox $User
    $OwnerMailbox.GrantSendOnBehalfTo += $UserMailbox.DistinguishedName
    Set-Mailbox $OwnerMailbox.alias -GrantSendOnBehalfTo $OwnerMailbox.GrantSendOnBehalfTo
    ——————–

    All that replaced by one simple expression.
    Thanks again!!!

Leave a Reply