Skip to content

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

The current article is the contention of the previous article, in which we review the task of adding an E-mail address to Exchange Online recipients using PowerShell. The focus of this article is how to perform the task of adding an additional E-mail address in a Bulk mode.

Adding E-mail addresses using Bulk mode

The notable advantage of “Bulk operation” is, that in a “single click,” we can update many “objects” such as an Exchange Online recipient at the same time without the need to address each recipient separately.

At the same time, this “notable advantage” can very easily become “notable disadvantage.”

If the “Bulk operation” is not tested and verified before we run it in our production environment, in case that the PowerShell bulk command implemented Improperly, it can cause considerable damage to our organization environment!

Performing Bulk tasks using PowerShell

The issue is when we “heavy tools” such as Bulk operations, is recommended that we understand exactly what the PowerShell Bulk command “do.”

My recommendation is, that before executing Bulk operations, try to test the “Bulk operation” in a “Lab” environment, or use to implement the Bulk operation on “test users.”

After we are sure that the PowerShell bulk command performs the operation correctly, and we run the required bulk command, it’s important that we will verify the “results” by checking if the affected “objects” (such as Exchange Online mailboxes) and there were configured correctly.

The useful tool – Whatif

A very useful and powerful PowerShell option that we can use when working with “Bulk command” is the option (the parameter) – Whatif.

Using the Whatif option, enable us to simulate the scenario of “what would have happened” if we run the “Bulk PowerShell command,” without implementing any changes to our environment.

My recommendation is to use as much as you can be the option of Whatif option, before “hitting” the key that would execute the Bulk PowerShell command, that can impact tens of hundreds or even thousands of mailboxes at the same time.

In the following examples, we run a “Bulk command” that spouse to “impact” all the existing Exchange Online mailboxes, by adding an additional E-mail address to each Exchange recipient.

To be able to “predict” what the bulk PowerShell command “will do,” we add the Whatif PowerShell parameter.

In our example, we can see that the “bulk operation” will successfully run on a specific Exchange mailbox such as “Angelina,” “Aretha” and “Beyonce.”

At the same time, we can see that the Bulk operation failed to update some Exchange recipients.

Looking at the Whatif results, we can see that the Bulk operation could not update specific Exchange mailboxes such as Adele’s mailbox.

PS C:\> $AllMailboxes = Get-Mailbox -ResultSize Unlimited
Foreach ($Mailbox in $AllMailboxes)
{
$NewAddress = $Mailbox. UserPrincipalName + "@o365pilot.com" # Create a new string that add a NEW E-mail address with the NEW domain suffix
$Mailbox.UserPrincipalName += $NewAddress # “Collect” all existing E-mail addresses + add the NEW E-mail address as an additional E-mail address (existing E-mail address will not be removed).
Set-Mailbox -Identity $Mailbox.Alias -EmailAddresses $Mailbox.EmailAddresses -whatif
}
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

+ FullyQualifiedErrorId : [Server=DB6PR0501MB2069,RequestId=25c4f399-2412-41c2-9a77-41af5911613e,TimeStamp=1/9/2017 11:43:30 AM] [FailureCategory=Cmdlet-InvalidOperationException] 4728449,Microsoft.Ex
change.Management.RecipientTasks.SetMailbox

+ PSComputerName : outlook.office365.com
The operation couldn't be performed because 'Alicia Keys' matches multiple entries.

+ CategoryInfo : NotSpecified: (:) [Set-Mailbox], ManagementObjectAmbiguousException

+ FullyQualifiedErrorId : [Server=DB6PR0501MB2069,RequestId=25c4f399-2412-41c2-9a77-41af5911613e,TimeStamp=1/9/2017 11:43:31 AM] [FailureCategory=Cmdlet-ManagementObjectAmbiguousException] 6E7A870C,Mi
crosoft.Exchange.Management.RecipientTasks.SetMailbox

+ PSComputerName : outlook.office365.com

What if: Setting mailbox "Angelina".
What if: Setting mailbox "Aretha".
What if: Setting mailbox "Beatles".
What if: Setting mailbox "Beyonce".

In our specific scenario, the PowerShell command cannot update Adele’s mailbox because the Adele user account considers as “Synchronized user account” that was synchronized to Exchange Online infrastructure from On-Premise Active Directory.

In this type of scenario, we will need to run the required “bulk operation” in the On-Premise environment (On-Premise Active Directory or Exchange on-premises) instead of Office 365 infrastructure.

You can read more information about the Directory synchronization environment in the article – Adding Email addresses using PowerShell | Office 365 | Part 3#13.

Working with test mailboxes (Lab Mailboxes)

When we implement a “bulk process,” the process run of a “group of objects” such as Exchange Online mailboxes.

In the following section, I would like to review the important need for creating a “pilot Exchange Online mailboxes,” which we can use as test mailboxes” for testing a specific Bulk operation.

To be able to test the impact of the bulk command, it’s recommended to create a “Test Exchange Online mailboxes,” that will serve as the “Array” that represents to real production objects.

Technically speaking, there are many methods which we can create an Array.

In our example, we “distinguish” the specific Exchange Online mailboxes that will serve as “Test mailboxes,” by marking them using the special character.

To distinguish these Exchange Online mailboxes from the rest of the mailboxes, we add to each of the “test mailboxes,” a custom attribute using the field named CustomAttribute1.

The text string that we use in our example is TestMailbox.

Step 1 – Creating the array

To create an array that includes all the “test Exchange Online mailboxes” that have the specific value in their CustomAttribute1, we use the Where statement, in which we ask to view only Exchange Online mailboxes, that their CustomAttribute1 field has the value of TestMailbox.

An example of the PowerShell command:

Get-Mailbox | Where {$_.CustomAttribute1 -eq 'TestMailbox'}

Step 2 – Define a variable that “store” the array members.

To be able to manipulate the “members” in the array, we define a variable which serves as a “logical container” that stores the Array members.

In our example, we define a variable named – $AllMailboxes, that store the results from a PowerShell filter search query.

An example of the PowerShell command:

$AllMailboxes = Get-Mailbox | Where {$_.CustomAttribute1 -eq 'TestMailbox'}

Later, we will use a PowerShell bulk command, that will “access” the information stored in the variable that created, and “do something” for each member in the Array.

Adding E-mail address in Bulk using the ForEach statement

In the following sections, we review the process of adding a NEW E-mail address in bulk mode to existing Exchange Online recipients, using a PowerShell script.

The “Bulk process” is implemented by involving a couple of “PowerShell components” such as – using PowerShell ForEach and Where statement, creating some variables that will store the Array member and each of the members, PowerShell cmdlets that import information from a CSV file, creating variables and so on.

In the following section, I provide a basic explanation about the PowerShell command syntax that we use.

In case you want to get more detailed information about the subject of ForEach statement Loop process, and the use of “variables” in the PowerShell environment, you can read the following articles:

In case you want to read more information about – how to use the PowerShell Where filter, for creating a filtered search query you can read the following articles:

Add additional E-mail address (Alias) using a NEW Domain name suffix to all Mailbox recipients | Bulk Mode

In the following section, we review the process of using PowerShell bulk script, that will perform the task of adding a NEW Alias E-mail address that uses the NEW domain name suffix, for each of our Exchange Online recipients.

  • Our company uses the public domain name – o365info.com
  • Our company purchased an additional domain name – o365pilot.com

At the current time, all the company users have an E-mail address that uses the domain
name suffix – “o365info.com”.

We were asked to implement the following tasks:

  • Add to all the company users (Exchange Online recipients), an additional E-mail address (proxy E-mail address) that includes the “NEW domain name” suffix – “o365pilot.com“.
  • The “Alias part” (the left part) of the NEW E-mail addresses, should be identical to the existing Alias that is used for the Primary E-mail address by each of the Exchange Online recipients.
  • The NEW E-mail address will not replace the existing primary E-mail address, but instead, will be added as an additional E-mail address (Alias, Proxy E-mail address).
  • All the existing Alias E-mail addresses and other address such as SIP address, of the Exchange Online recipients, will be kept.

In the following diagram, we can see the structure of the organization E-mail address and the required results:

Add additional E-mail address Alias using a NEW Domain name to all recipients PowerShell Bulk Mode

For example,

  • The current Primary E-mail address of user named John is– John@o365info.com
  • We want to add an additional E-mail address (Proxy E-mail address) to the recipient
    named John.
  • The additional E-mail address will be the following E-mail address – “John@o365pilot.com.

In the following diagram, we can see an example of the requested result, for a specific Exchange Online recipient named – John.

Add additional E-mail address Alias using a NEW Domain name to all recipients PowerShell Bulk Mode

The PowerShell command structure

To be able to run the required update for all the Exchange Online recipients, we will use a PowerShell ForEach statement (with a combination of variables), which will Loop via all existing Exchange Online mailboxes, and run the required task of – adding a new E-mail Alias, for each of the Exchange Online mailboxes.

Step 1: We use the variable named $AllMailboxes for storing information about all the existing Exchange Online mailboxes.

Step 2: We define a variable named $NewAddress, that is created for storing the NEW E-mail address. The NEW E-mail address is created by using a combination of the existing Exchange recipient Alias ($Mailbox.Alias) + the string with the “NEW domain name suffix @o365pilot.com”.

Step 3: We create an “Array” that will store all the recipient existing E-mail address + the New E-mail address in the following way – $Mailbox.EmailAddresses += $NewAddress
We use this step, for avoiding a scenario in which the existing E-mail address will be deleted and replaced by the NEW E-mail address.

Step 4: We ask from PowerShell, to “set” a NEW E-mail addresses (Alias E-mail address) for each recipient, by adding the New E-mail address (the NEW E-mail address with the domain name suffix o365pilot.com) to the existing array of E-mail addresses.

$Domainsuffix = Read-Host "Type the name of the Domain name suffix"
$AllMailboxes = Get-Mailbox -ResultSize Unlimited
Foreach ($Mailbox in $AllMailboxes)
{
# Creating NEW E-mail address that contracted in the following way: Take the existing recipient Alias name + use the NEW Domain name as a domain suffix + “Bind” the Alias name + the NEW Domain name suffix.
$NewAddress = $Mailbox.Alias + "@$Domainsuffix"
# “Store” all existing E-mail addresses + add the NEW E-mail address as an additional E-mail address.
$Mailbox.EmailAddresses += $NewAddress
# Assign the NEW E-mail address to the existing Exchange Online recipient
Set-Mailbox -Identity $Mailbox.Alias -EmailAddresses $Mailbox.EmailAddresses #-whatif
}

Playing with the variable that defines the recipients “Array”

The variable that defines the Exchange Online “recipients Array” $AllMailboxes is very “flexible”

We can define many different types of Exchange Online recipient as the member or the “Array.”

Option 1

Define a scenario, in which we want that the bulk command will add an additional E-mail address to all “Exchange Online mailboxes.”

In this case, the Bulk command adds the additional E-mail address to the various types of Exchange Online Mailbox recipients such as – Room mailbox, shared Mailbox and User mailbox.

$AllMailboxes = Get-Mailbox -ResultSize Unlimited

Option 2

Define a scenario, in which we want that the bulk command will add additional E-mail address only to “Exchange Online user mailboxes.”

$AllMailboxes = Get-MailBox -Filter '(RecipientTypeDetails -eq "UserMailbox")'

Option 3

Define a scenario, in which we want that the bulk command will add an additional E-mail address to only all existing Exchange Online recipients.

In this scenario, the Bulk command adds an additional E-mail address to various types of Exchange Online recipients such as – Groups, mail contacts, Mailbox recipient, etc.

$AllMailboxes = Get-recipient -ResultSize Unlimited

Option 4

Define a scenario, in which we want that the bulk command will add an additional E-mail address to Exchange Online recipients, besides recipients that are synchronized from Exchange on-Premises environment.

$AllMailboxes = Get-recipient -ResultSize Unlimited | Where {$_.Capabilities -nq "MasteredOnPremise"}

Option 5

Define a scenario, in which we want that the bulk command will add an additional E-mail address to Exchange Online recipients Exchange Online mailboxes that defined as a “Test mailbox.”

In this case, the bulk command will update only Exchange Online mailboxes that their customattribute1 value is “TestMailbox.”

$AllMailboxes = Get-Mailbox | Where {$_.CustomAttribute1 -eq 'TestMailbox'}

Replace Primary E-mail address Domain name suffix with a NEW Domain name suffix | Bulk mode

In the following section, we review the process of using a PowerShell bulk script, that will perform the task of – replacing the existing Primary E-mail address with a NEW Primary E-mail address that uses a different domain name suffix.

  • Our company uses the public domain name – o365info.com
  • Our company purchased an additional domain name – o365pilot.com

At the current time, all the company users have an E-mail address that uses the
domain name suffix – o365info.com.

We were asked to implement the following tasks:

  • Replace the current primary E-mail address that uses the domain name com with a NEW primary E-mail address, that uses the domain name suffix – o365pilot.com
  • The Alias name of the Exchange recipient (the right part of the E-mail address) will stay the same. In other words, we would like to keep the existing Alias name from the current Primary E-mail address and replace the “left part” (domain name suffix) with a NEW domain name suffix.
  • The previous Primary E-mail address will not be deleted but instead, saved as an Alias E-mail address
    (additional E-mail address).
  • All the existing Alias E-mail addresses and other address such as SIP address, of the recipients, will be kept.

In the following diagram, we can see the structure of the organization E-mail address and the required results:

Replace the existing primary email address with a NEW primary E-mail address -01

In the following diagram, we can see an example of the requested result for a specific Exchange Online recipient named – John.

Replace the existing primary email address with a NEW primary E-mail address -02

The PowerShell command structure

The PowerShell command that we use in this scenario is like the PowerShell command that we use in the previous scenario.

The main difference is, that in this case, we add an additional PowerShell command, that sets
the primary E-mail address of each recipient to use the NEW E-mail address.

In our example, we wish to replace the existing Primary E-mail address
using the “o365pilot.com” domain suffix.

Set primary E-mail address

To set the primary E-mail address, we use the PowerShell parameter WindowsEmailAddres

The PowerShell syntax that we use in our scenario is:

Set-Mailbox -Identity $Mailbox.Alias -WindowsEmailAddress $NewAddress

Creating the “NEW E-mail address” structure

To create the required naming convention of the new E-mail address, we use the same “trick
that was used in the previous scenario.

We create a variable that creates a NEW E-mail address.
The “left part” of the E-mail address (the “Alias”) is taken from the existing Alias that each Exchange recipient has.

The PowerShell will “bind” the existing Alias to the NEW domain name suffix (the right part of E-mail address).

The syntax that we use is – $NewAddress = $Mailbox.Alias + “@o365pilot.com”

The PowerShell script syntax that we use is:

$AllMailboxes = Get-Mailbox -ResultSize Unlimited
Foreach ($Mailbox in $AllMailboxes)
{
# Creating NEW E-mail address that contracted in the following way: Take the existing recipient Alias name + use the NEW Domain name as a domain suffix + “Bind” the Alias name + the NEW Domain name suffix.
$NewAddress = $Mailbox.Alias + "@o365pilot.com"
Set-Mailbox -Identity $Mailbox.Alias -WindowsEmailAddress $NewAddress #-whatif
}

The next article in the current article series

Adding Email addresses using PowerShell – Import from CSV file | Bulk mode | Office 365 | Part 5#13

o365info Team

o365info Team

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

This Post Has 0 Comments

Leave a Reply

Your email address will not be published. Required fields are marked *