Skip to content

Adding Email addresses using PowerShell | Office 365 | Part 3#13

Our focus in this article is – the administrative task of “adding” E-mail address using the PowerShell cmdlets Set-Mailbox. The subjects that we will review are:

  1. The two methods of adding a NEW E-mail address – replacing the existing email address vs. adding a NEW E-mail address.
  2. The different type of E-mail address and other address.
  3. The subject of a Primary E-mail address and Proxy E-mail address.

The current article series

The current article series includes 13 articles.

In case that you scratch your head, and think something like – “Why in god’s name I need to read so much boring information about, managing E-mail address using PowerShell”?

Or other taught such as – “I need a quick and fast answer to my needs!”

My answers are as follows:

Answer 1 – many times, I get customer request that relates to various tasks of managing E-mail address using PowerShell, and I found that there is not a lot of information on this topic. Especially, regarding Office 365 and Exchange Online work environment.

Answer 2 – you don’t have to read all the articles. Each article relates to a different aspect of
managing E-mail address such as – view and export information about E-mail addresses, add E-mail addresses, remove E-mail addresses, search for E-mail addresses and so on.

At the beginning of each article in the current article series, you can find a “table of content,” that will help you to navigate to the specific subject that is most relevant to you.

Manage E-mail address using PowerShell – the table of content

Answer 3 – for those of us that love to go straight to the point, you can use the first article in the current article series. The main purpose of the first article is, to enable a quick view of PowerShell syntax examples, with too many details or long explanation about “what happens behind the scenes.”

Answer 4 – at the bottom of each article, I add a link to a “Menu based PowerShell script,” that will simplify the task of executing various management tasks such as – export information about existing E-mail addresses, search for specific E-mail addresses, add an additional alias to the existing Exchange Online recipients and so on.

Manage E-mail address | cloud environment vs. Exchange Hybrid or Directory synchronization environment

The information on the current article series can be applied only in a scenario in which your Office 365 environment is a “cloud only” or “cloud native” environment.

In case that your environment considers as the Exchange Hybrid environment or, Directory synchronization environment, the process of “addressing” recipient who is synchronized from On-Premise Active Directory to the “cloud” (Azure Active Directory and Exchange Online) will need to be implemented by using your On-Premise infrastructure.

In a Directory synchronization environment, which doesn’t use local Exchange on-Premises, the E-mail address management needs to be implemented via the On-Premise Active Directory user and computer tool (or by using PowerShell).

In the Exchange Hybrid environment, the E-mail address management needs to be implemented via the Exchange on-Premises management interface or by the Exchange on-premises PowerShell console.

You can read more information about this subject at the bottom of the article.

Exchange Online recipients and the PowerShell command Set-mailbox

The term “Exchange Online recipients” is a wide term that includes many types of recipients such as “Mailbox recipient,” “Group recipient,” “Contact recipient” and more.

In the article – Introduction to the various type of Exchange Online recipients | PowerShell cmdlets | Office 365 | Part 8#13, we review in more details each type of the “Exchange Online recipients, and the difference between them.

Most of the time, the administrative task of adding or removing E-mail addresses is implemented by “addressing” the “Exchange Online mailbox recipient.”

Technically speaking, there are four classifications of “mailbox recipient” – User mailbox, Shared mailbox, Room mailbox, and equipment Mailbox.

Most of the time, the management tasks that relate to “adding NEW E-mail address” are implemented towards that “USER mailbox recipient.”

Demonstrating the task of adding NEW E-mail address - Exchange Mailbox recipient

The PowerShell commands that we use for managing Exchange Online “mailbox recipient,” are:

The PowerShell cmdlets Set-Mailbox, used for implementing the following tasks:

  • Add E-mail address.
  • Remove (or replace) E-mail address.

The PowerShell cmdlets Get-Mailbox, used for implementing the following tasks:

  • View and export information about E-mail addresses.
  • Search for specific E-mail addresses.

The challenge of adding an E-mail address

Implementing the task of adding an E-mail address to a “recipient,” in Office 365 (Exchange Online), can be considered as confusing because of two main reasons:

  1. The two methods for adding a NEW E-mail address using the Set-Mailbox cmdlet (adding E-mail address vs. replacing the existing email address).
  2. The different “behavior“ of Primary E-mail address vs. Proxy E-mail address.
Set-mailbox adding versus replacing E-mail address -01

Replace the existing email address vs. adding an additional E-mail

In the Exchange Online environment, the task of adding (or removing) E-mail address, is implemented by using the PowerShell cmdlet Set-Mailbox.

Regarding the task of adding an E-mail address, the PowerShell cmdlet Set-Mailbox, provide us two different methods:

  • Method 1#2 – Replacing (removing) existing E-mail address with “other” E-mail addresses.
  • Method 2#2 – Adding NEW E-mail address to the existing “set” of E-mail addresses.

The difference between these two methods is not so clear, and could very easily lead to a scenario, in which by mistake, we remove (delete) existing E-mail address, in the process of adding a new E-mail address (NEW E-mail address replaces the existing email address).

Method 1 – Replacing (removing, deleting) existing E-mail address with the NEW E-mail address that we provide.

When we use the default syntax of the Set-Mailbox PowerShell command + addressing the property EmailAddress, the result can be “translated” to one of the following options:

  1. Removing (deleting) existing E-mail addresses by implementing a process in which the NEW E-mail address replaces existing recipient E-mail addresses.
  2. Add a NEW E-mail address to the Exchange Online recipient to existing “array” of E-mail addresses.

In Office 365 (Exchange Online) based environment, the phenomena of “removing existing
E-mail addresses” is even more extensive.

In an Office 365 environment, the method of using the default Set-Mailbox PowerShell command syntax will “removing an existing Alias E-mail address,” + lead to unexpected results such as- deletion of the original onMicrosoft E-mail address, x500 address, and the deletion of SIP address.

We will review this subject in more details in the section – Three methods that can be used for setting Exchange Online mailbox primary E-mail address.

Add additional E-mail address to existing E-mail address -03

Method 2 – Adding additional E-mail address to the “set” of existing E-mail addresses.

The second method of adding the NEW E-mail address is less “aggressive” because, in this method, the NEW E-mail address will be added to the existing E-mail addresses “array,” instead or deleting or removing existing E-mail address.

In this method, we use the PowerShell parameter @{add, and provide one or more E-mail address that will be added to the Exchange recipient.

Add additional E-mail address to existing E-mail address -03

Primary E-mail address vs. Alias (Proxy) E-mail address

In this section, we review the subject of primary E-mail address vs. the additional E-mail address that described as – Proxy E-mail addresses or Alias E-mail addresses.

Primary E-mail address versus Alias Proxy E-mail address

Just a brief reminder, a Primary E-mail address is the E-mail address that “represent” the recipient when he sent an E-mail address to other recipients. This is the E-mail address that the “another recipient” will see.

The proxy E-mail address is additional E-mail addresses, that can be “attached” to the recipient.
The proxy E-mail addresses use mainly for “incoming mail.”

Other recipients can send E-mail to the “Proxy E-mail address,” and the recipient who “own” the Alias E-mail address, get the E-mail because he is the “owner of the specific Proxy E-mail address.

  • Each recipient can have only one “Primary E-mail address.”
  • Each recipient can have zero, one or many Alias E-mail addresses.

Comparison table Primary E-mail address vs. Proxy E-mail address.

Primary E-mail addressProxy (Alias) E-mail address
Only oneZero or unlimited number (none, one or multiple).
Defended using SMTP: prefix, and by using capital lettersDefended using the SMTP: prefix, and by using small caps
Has a “dedicated” PowerShell propertyDoesn’t have a “dedicated” PowerShell property. The proxy E-mail addresses “stored” In the recipient’s property EmailAddresses, together will all the rest of the recipient address such as – SIP address, x500 address, and including the Primary E-mail address.
This E-mail address “represents” the recipient when he sends E-mails to another recipient and considers as the “reply address.”Exchange recipient cannot send E-mail address using his “additional E-mail address) Alias but can “accept” E-mail message sent to his Alias E-mail address.

Adding E-mail address | Primary E-mail address vs. Proxy E-mail address

The “thing” is that in an Office 365 based environment, PowerShell made sure, that the task of adding the NEW E-mail address is a little confusing.

When we add a NEW E-mail address to Exchange mailbox, we need to define the E-mail address as a Primary E-mail address or, as a Proxy E-mail address.

In the Exchange on-premises environment, the PowerShell cmdlet Set-Mailbox, include a “dedicated” parameter named PrimarySmtpAddress, that is used to set the “primary E-mail address.”

In the Exchange Online environment, the PowerShell cmdlet Set-Mailbox doesn’t support this “special” parameter, that is used for setting the primary E-mail address.

We will need to use other methods to set the primary E-mail address of the Exchange Online recipient, such as setting the value of a property named WindowsEmailAddress

Later in the article, we will review additional methods for setting primary E-mail address in Exchange Online based environment.

“Where is the information about mailbox E-mail addresses is stored

  • Each Office 365 users, can have one or multiple E-mail addresses.
  • The E-mail address could be SMTP E-mail address or another type of E-mail address such as x500 E-mail address.
  • Each Office 365 users, can have “other types of address” such as – SIP address that is used for the Skype for business infrastructure.
  • In Office 365 environment the user UPN (User Principal Name) defines the default Exchange Online recipient SMTP E-mail address.

In Exchange Online infrastructure, the information about the Exchange recipient address is saved in a couple of property’s fields.

Exchange Online recipient | Information about – Primary E-mail address

The Exchange Online recipient primary E-mail address is saved in a dedicated property field named PrimarySmtpAddress, and in addition, in a property field named WindowsEmailAddress.

We will not get into a detailed review of the difference between these two properties field.

The main thing that I would like to mention is, that in a scenario in which we want to replace the existing Primary email address (set a NEW primary E-mail address) by using the Set-Mailbox PowerShell command:

  1. Although the Exchange Online mailbox recipient has the property – “Primary E-mail address,” when using the Set-Mailbox command, we cannot address “directly” the Exchange Online mailbox property named PrimarySmtpAddress. In other words, we cannot “Set” the PrimarySmtpAddress property.
  2. To be able to “Manage” the Exchange mailbox recipient Primary E-mail address, we can address the Exchange Online mailbox property named WindowsEmailAddres.

Exchange Online recipient | Email Addresses property | The main “store” of Exchange Online recipient “addresses

All the E-mail addresses of Exchange Online recipients are stored in a property field
named EmailAddresses.

Where is the information about mailbox E-mail addresses is stored -02

The property (attribute) named EmailAddresses, serve as a “logical container” that “hold” all the various user E-mail addresses such as – Primary SMTP E-mail address (although the primary E-mail address has a dedicated property field), Alias SMTP E-mail address, x500 E-mail address, and SIP address.

Where is the information about mailbox E-mail addresses is stored -03

In the following example, we use a PowerShell command for displaying information about the various property fields that were mentioned:

Get-Mailbox Billy | FL PrimarySmtpAddress,EmailAddresses,WindowsEmailAddress
  • We can see that the content of the WindowsEmailAddress property field is identical to the PrimarySmtpAddress property field
  • We can see that the EmailAddresses property field includes various types of E-mail address such as – SMTP E-mail address, x500 E-mail address and SIP address.

PowerShell console output example:

PS C:\script> Get-Mailbox Billy | FL PrimarySmtpAddress,EmailAddresses,WindowsEmailAddress

PrimarySmtpAddress : Billy@o365info.com

EmailAddresses : {smtp:Billy@o365info2.mail.onmicrosoft.com, X500:/o=First Organization/ou=External (FYDIBOHF25SPDLT)/cn=Recipients/cn=Billya76, SIP:Billy@o365info.com, SMTP:Billy@o365info.com...}
WindowsEmailAddress : Billy@o365info.com

The different terms that we use for describing non-Primary E-mail address

In the current article series, we will use a couple of terms that describe a non-Primary E-mail address.

It’s important to me to emphasize that all the following terms are “identical”:

  • Secondary E-mail address.
  • Alias E-mail address.
  • Proxy E-mail address.
  • Additional E-mail address.
The different terms that we use for describing non-Primary E-mail address

Three methods that can be used for setting Exchange Online mailbox primary E-mail address

Although that in Exchange Online we don’t have a dedicated PowerShell parameter for managing the Primary E-mail address, there are three methods that we can use to set a NEW Primary E-mail address.

If we want to use a more accurate term, we should use the term “replacing” primary E-mail address, because each Exchange recipient can have only one primary E-mail address.

When we set a NEW primary E-mail address, the NEW primary email address must replace (remove) the previous Primary E-mail address.

In other words, we can say that a NEW primary E-mail address, Inherits the place of the previous primary E-mail address.

Method 1#3 – Adding (replacing) primary E-mail address | Using the default command

In this method, all we need to do is, just use the default parameter of the Set-Mailbox PowerShell command, by using the following syntax:

PowerShell command syntax:

Set-Mailbox <Identity> -EmailAddress <Email Address>

PowerShell command example:

Set-Mailbox Bob -EmailAddress BobNewEmail@o365info.com

Even though we didn’t mention that the E-mail address that we provide (BobNewEmail@o365info.com in our scenario) should be the NEW primary E-mail address, PowerShell “interpret” the syntax, as though we ask him to set the specified E-mail address as a “NEW Primary E-mail address.”

Later, we will discuss in more detail what will happen to the previous primary E-mail address and the rest of the address.

Method 2#3 – Adding (replacing) primary E-mail address | Set the property – WindowsEmailAddress

In this method, we address other Exchange Online mailbox property named WindowsEmailAddress.

The Exchange Online mailbox property WindowsEmailAddress, contains the recipient Primary E-mail address.

In case that we set the value of the E-mail address stored in the WindowsEmailAddress property, the Exchange Online recipient primary E-mail address is also updated.

PowerShell command syntax

Set-Mailbox <Identity> -WindowsEmailAddress <Email Address>

PowerShell command example

Set-Mailbox Bob -WindowsEmailAddress BobNewEmail@o365info.com

Method 3#3 – Adding (replacing) primary E-mail address | Using the SMTP prefix

In this method, we “mark” a specific E-mail as a “primary E-mail address.”
The way that we use for “telling” PowerShell that we want to define a specific E-mail address as a “Primary E-mail address” is, by using the “SMTP:” prefix using a capital letter.

The syntax is implemented by using the SMTP prefix before the E-mail address.

For example SMTP:E-mail address

An example of the PowerShell command, syntax:

PowerShell command syntax

Set-Mailbox <Identity> -EmailAddress SMTP:<primary E-mail address>

PowerShell command example

Set-Mailbox Bob -EmailAddress SMTP:Bob-NEW01@o365info.com

Using the @{add PowerShell parameter for adding a primary email address

Theoretically, we can assume that we can use the PowerShell Method @{add, for adding a Primary E-mail address.

In reality, this option is not available.

In the following example, we try to use the PowerShell parameter @{add for adding a primary E-mail address to a recipient named Christina, by using the SMTP prefix with a capital letter:

Set-Mailbox -Identity Christina -EmailAddresses @{add="SMTP:" + "New-Email@o365info.com"}

The result is the following error:

xxx 
Set-Mailbox -Identity Christina -EmailAddresses @{add="SMTP:" + "New-Email@O365INFO.COM"}

There are multiple primary SMTP addresses. Please ensure there is only one primary address for each address type.

+ CategoryInfo : NotSpecified: (Christina:ADObjectId) [Set-Mailbox], DataValidationException

In case that we try to use the method of adding and removing values (@{add or @{remove), by trying to remove an existing Primary E-mail address, so later we will be able to add a NEW Primary E-mail address such as the following PowerShell command:

Set-Mailbox Christina -EmailAddresses @{Remove="Christina@o365info.com"}

The following error message appears:

PS C:\script> Set-Mailbox Christina -EmailAddresses @{Remove="Christina@o365info.com"}

There is no primary SMTP address.

+ CategoryInfo : NotSpecified: (Christina:ADObjectId) [Set-Mailbox], DataValidationException

Two methods that can be used for setting Exchange Online Mailbox Alias E-mail address

As mentioned, there are two types of “SMTP E-mail addresses” – Primary E-mail address, and secondary (Alias or Proxy) E-mail addresses.

In this section, we review the method which we can use for adding an Alias (Proxy) E-mail address to the Exchange Online recipient.

There are two available methods that we can use for adding a Proxy E-mail address.

Method 1 – Set E-mail address using the @{add method

In this option, we use a PowerShell “method” for adding or removing “values,” from an “object property field” that can contain multiple values.

In our specific scenario, the “values” that we want to add (or remove) are the recipient E-mail addresses.

The Exchange Online mailbox property that “contain” the multiple values (one or more recipient E-mail addresses) is Exchange Online mailbox property field named EmailAddresses.

To be able to add value or remove (delete) from the “array” of E-mail addresses, we use the PowerShell syntax:

  • @{add “Value” – for adding additional values
  • @{remove “Value” – for removing (deleting) existing values

This is the recommended method because, when using this PowerShell syntax (the option of @{add), the “NEW value” (the E-mail address in our case) will not replace or delete existing
E-mail address.

EmailAddresses property as a property field, that can contain multiple values

Method 2 – Set E-mail address without using the @{add method | Two E-mail address

This method is less recommended, but it’s important that we are familiar with this option.

In the following diagram, we can see an example of a PowerShell command, in which we use the EmailAddresses parameter, and providing three E-mail addresses.

In this case, PowerShell will relate to the “first” E-mail address (number 1) as the Primary E-mail address, and to the rest of the E-mail addresses (number 2 and number 3) as a Proxy E-mail address.

The “issue” with the method is, that PowerShell will remove (delete) existing E-mail address, and “place” the NEW E-mail address that we provide, as a replacement of the previous E-mail address (remove existing E-mail addresses).

Adding two or more E-mail addresses

Replacing existing E-mail address with a NEW E-mail address

In the following section, we review how to implement a scenario, in which his main character is Replacing (removing) existing E-mail address and providing a NEW E-mail address instead.

Notice that in this scenario, the PowerShell command that we use will remove (delete) any
the existing E-mail address that the recipient has, besides of the existing Primary E-mail address that will be saved as an Alias E-mail address.

To replace the existing email address, we use the PowerShell Set-Mailbox without using the method of “@{add” or “@{remove”.

A little bit about how PowerShell understands the information about E-mail addresses

When, we use the Set-Mailbox command with the “EmailAddresses” parameter, the
Set-Mailbox command is based on the following defaults:

In case that we provide only one E-mail address, the E-mail address that we provide will be considered as Primary E-mail address and will replace the current primary E-mail address.

The existing Primary E-mail address will not be deleted, but instead, will be configured
as Alias E-mail address.

Note – all the rest of the recipient E-mail address will be deleted!

Set E-mail address without using the @ add method - 01

In case that we provide two or more E-mail addresses, the “first E-mail address” that we provide, will be considered as Primary E-mail address and will replace the current primary E-mail address.

The “rest” of the E-mail addresses will be configured as Alias (Proxy) E-mail addresses.

Set E-mail address without using the @ add method - 02

What will happen to exist Proxy E-mail addresses?

Many times, the recipient whom we “address”, already have an existing Alias E-mail address or other address such as SIP address.

In case that we provide two E-mail addresses, the first E-mail address will “replace” the current
primary E-mail address.

The Proxy E-mail address that we provide with the PowerShell command, will be added to the recipient.

Note that when using this method, any existing proxy E-mail address will be removed (deleted)!

Set E-mail address without using the @ add method - 03

The outcome of using Set E-mail address without using the @{add method | Three optional scenarios

To be able to understand better the result of using the use the PowerShell Set-Mailbox command using the EmailAddresses parameter, but without using the method of @{add let’s use a couple of demonstrations.

Scenario characters:

In the next section, we demonstrate a couple of “Set E-mail address” scenarios, which will be implemented on Exchange Online recipient named – Angelina

Angelina has the following E-mail addresses:

  • Primary E-mail address – Angelina@o365info.com
  • Alias E-mail addresses – Angelina has two aliases E-mail addresses
    • The default Office 365 onMicrosoft E-mail address – Angelina@o365info2.onmicrosoft.com
    • Additional E-mail address – Angelina-Alias01@o365info.com
  • SIP address- Angelina@o365info.com
Angelina E-mail addresses

Scenario 1 – Set E-mail address without using the @{add method | One E-mail address

Scenario description

We would like to “replace” the primary E-mail address of the Exchange Online recipient.

In this scenario, we use the Set-Mailbox command with the EmailAddresses parameter and provide only a single E-mail address.

In our example, the single E-mail address is: Angelina-NEW01@o365info.com

The PowerShell command:

Set-Mailbox Angelina -EmailAddress Angelina-NEW01@o365info.com

The results are as follows:

  • The NEW E-mail address (Angelina-NEW01@o365info.com) replaces the current Primary E-mail address.
  • The “old” Primary E-mail address, saved as an Alias E-mail address (additional E-mail address, but not
    a primary E-mail address).
  • All the “other E-mail addresses” – Alias E-mail address, OnMicrosoft E-mail address and SIP address are removed (deleted)!
PS C:\script> Get-Mailbox Angelina | Fl Alias,PrimarySmtpAddress,EmailAddresses

Alias : Angelina

PrimarySmtpAddress : Angelina-NEW01@o365info.com

EmailAddresses : {smtp:Angelina@o365info.com, SMTP:Angelina-NEW01@o365info.com}

Scenario 2 – Set E-mail address without using the @{add method | Two (or more) E-mail addresses

Scenario description

We would like to “replace” the primary E-mail address of Exchange Online recipient + add NEW Alias E-mail address.

In this scenario, we use the Set-Mailbox command with the EmailAddresses parameter and provide two E-mail addresses.

In our example, the E-mail addresses are:

  • Angelina-NEW01@o365info.com
  • Angelina-Alias02@o365info.com
Set-Mailbox Angelina -EmailAddress Angelina-NEW01@o365info.com,Angelina-AliasTest02@o365info.com

The results are as follows:

The PowerShell command Set-Mailbox understands that the first E-mail address is the primary E-mail address, and all the rest of E-mail addresses should be configured as a “secondary“ (Alias) E-mail addresses.

  • The NEW E-mail address (Angelina-NEW01@o365info.com) replaces the current Primary E-mail address.
  • The “old” Primary E-mail address saved as an Alias E-mail address (additional E-mail address, but
    not a primary E-mail address).
  • The “second E-mail address” that we use in the command (Angelina-Alias02@o365info.com) was added as an additional Alias E-mail address.
  • All the “other E-mail addresses” – Alias E-mail address, OnMicrosoft E-mail address and SIP address are removed (deleted)!
PS C:\> Get-Mailbox Angelina | Fl Alias,PrimarySmtpAddress,EmailAddresses

Alias : Angelina

PrimarySmtpAddress : Angelina-NEW01@o365info.com

EmailAddresses : {smtp:Angelina@o365info.com, smtp: Angelina-Alias01@o365info.com, SMTP:Angelina-NEW01@o365info.com}

Scenario 3 – E-mail address without using the @{add method | Two E-mail addresses + Define which E-mail address to use a primary E-mail address

In this scenario, we use the Set-Mailbox command with the EmailAddresses parameter and provide three E-mail addresses.

In our example, the E-mail addresses are:

  • Angelina-NEW01@o365info.com (should be configured as the primary E-mail address).
  • Angelina-Alias02@o365info.com
  • Angelina-Alias03@o365info.com

The main difference is that this time; we don’t want to let PowerShell decide by himself, which E-mail address will be defended as the “Primary E-mail address”.

Instead, we want to “instruct” PowerShell what E-mail address to use as a Primary E-mail address.

To be able to implement this scenario, we use the prefix SMTP (with capital letters).
When we use the SMTP prefix, PowerShell “understand” that the following E-mail address should be configured as a Primary E-mail address.

The PowerShell command syntax that we use is:

Set-Mailbox Angelina -EmailAddress Angelina-Alias02@o365info.com,Angelina-Alias03@o365info.com,SMTP:Angelina-NEW01@o365info.com

Notice that the E-mail address that we want to set as primary E-mail address is not the first
E-mail address.

The results are as follows:

  • The NEW E-mail address (Angelina-NEW01@o365info.com) replaces the current Primary E-mail address.
  • The “old” Primary E-mail address saved as an Alias E-mail address (additional E-mail address, but not a primary E-mail address).
  • The “second E-mail address” and the third E-mail address that we use in the command (Angelina-Alias02@o365info.com and Angelina-Alias03@o365info.com) was added as an additional Alias E-mail address.
  • All the “other E-mail addresses” – Alias E-mail address, OnMicrosoft E-mail address and SIP address are removed (deleted)!
PS C:\script> Get-Mailbox Angelina | Fl Alias,PrimarySmtpAddress,EmailAddresses

Alias : Angelina

PrimarySmtpAddress : Angelina-NEW01@o365info.com

EmailAddresses : {smtp:Angelina@o365info.com, SMTP:Angelina-NEW01@o365info.com, smtp:Angelina-Alias03@o365info.com, smtp:Angelina-Alias02@o365info.com}

How to recover from a scenario in which SIP address deleted by accident?

In a case that you were not aware of the possible consequences of using the Set-Mailbox command with the “EmailAddresses” parameter, and your experience as a scenario in which the SIP address was removed, you can add again the SIP address by using the following PowerShell command syntax.

PowerShell command syntax:

Set-Mailbox <identity> -EmailAddresses SIP:<SIP Address>

PowerShell command example:

Set-Mailbox Angelina -EmailAddresses SIP:Angelina@o365info.com

Note – I’m not aware of a way in which we can add SIP address, via the Exchange Online admin web-based interface.

Add an additional E-mail address using the “@{add” method

As mentioned in the previous section, the “formal method” that we use for adding an additional E-mail address is implemented by using the PowerShell command Set-Mailbox using the method of @{add syntax.

When using the @{add PowerShell method, the E-mail address that we specify is added to the existing “E-mail addresses array” as an additional E-mail address.

Add additional Alias (Proxy) E-mail address to a recipient

To add an additional E-mail address to a recipient without “impact” existing E-mail addresses, we can use the following syntax.

PowerShell command syntax:

Set-Mailbox <identity> -EmailAddresses @{add="<E-mail address>"}

PowerShell command example:

Set-Mailbox Angelina -EmailAddresses @{add="Angelina-Alias11@o365info.com"}

In case we need to add multiple E-mail addresses, we can separate each E-mail address with a comma.

For example:

Set-Mailbox Angelina -EmailAddresses @{add="Angelina-Alias11@o365info.com","Angelina-Alias12@o365info.com"}

General tip – The @{add PowerShell command can be replaced with the ‘+’ shortcut:

PowerShell command syntax:

Set-Mailbox <identity> -EmailAddresses @{“+”="<E-mail address>"}

PowerShell command example:

Set-Mailbox Angelina -EmailAddresses @{“+”=" Angelina-Alias11@o365info.com"}

Updating Exchange Online mailbox properties in the directory synchronization environment

In the current article series, we review many business scenarios, which relate to the subject of
E-mail address management in Office 365 and Exchange Online based environment.

The important thing that I would like to emphasize is, that in case that your infrastructure is based on Directory synchronization environment or Exchange Hybrid environment, we can not use “Exchange Online PowerShell” for implementing configuration updates of “cloud objects” such as Office 365 user accounts or Exchange Online mailboxes.

We will not provide a detailed answer for this “limitation” but just briefly explain that in a Directory synchronization environment, the On-Premise Active Directory is the “source of authority.”

Although in practice when Office 365 has a license of Exchange Online mailbox, the “ownership” of the Office 365 user account “belong” to the On-Premise Active Directory.
The Office 365 user account that is synchronized from On-Premise Active Directory consider as a “read-only object.”

For this reason, in a Directory synchronization, we can not “directly access” cloud object such as Exchange Online mailbox and try to add or update some property (such as E-mail address in our case).
In a Directory synchronization environment, any update to synchronized Office 365 user accounts (that have an Exchange Online mailbox), should be implemented via the On-Premise Active Directory or Exchange on-premises and not via Exchange Online.

To demonstrate this type of scenario, we use the following example:

Scenario description

  • Adele Office 365 user accounts are a synchronized user account from On-Premise Active Directory.
  • Adele has Exchange Online license.

We would like to add an additional E-mail address to the Adele Exchange Online mailbox.

We use the following PowerShell command:

Set-Mailbox Adele -EmailAddress Adele-NEW01@o365pilot.com -WhatIf

We get the following error:

The operation on mailbox "Adele" failed because it's out of the current user's write scope. The action 'Set-Mailbox', 'EmailAddresses', can't be performed on the object 'Adele' because the object is being

synchronized from your on-premises organization. This action should be performed on the object in your on-premises organization.

+ CategoryInfo : InvalidOperation: (Adele:ADObjectId) [Set-Mailbox], InvalidOperationException

The error message that appears is not so clear.

The meaning of the message “it’s out of the current user’s write scope” in simple words is, that the update could not be implemented because Adele Exchange mailbox is “attached” to a synchronized Office 365 user account.

Updating Exchange Online mailbox properties in Directory synchronization environment

In case that you need to update the E-mail address of the recipient who is synchronized from the Exchange on-premises environment, you will need to use the “Exchange on-Premises PowerShell console.”

From the Exchange on-premises perspective the recipient considers as “Remote mailbox.”
For example, in case that we need to update the Primary E-mail address of Exchange Online mailbox recipient, which was synchronized from Exchange on-Premises, we will need to run the command from Exchange on-Premises PowerShell console using the following syntax.

Update Primary E-mail address of Remote mailbox | Exchange Hybrid

PowerShell command syntax

Set-RemoteMailbox <Mailbox> -EmailAddresses <Primary E-mail address> -EmailAddressPolicyEnabled $false

PowerShell command example

Set-RemoteMailbox John -EmailAddresses Jhon@o365info.com 
-EmailAddressPolicyEnabled $false

The next article in the current article series

Adding Email addresses using PowerShell – Bulk mode | Office 365 | Part 4#13

o365info Team

o365info Team

This article was written by our team of experienced IT architects, consultants, and engineers.

This Post Has One Comment

  1. Like the previous commenter the formatting is a little distracting but the content is excellent and for which I thank you. One minor point is the use of “small caps” when you are referring to “lower case” lettering.

Comments are closed.