Add-SMTPAddresses.ps1 – Bulk Add SMTP Addresses to Office 365 Mailbox Users

Reading Tim McMichael’s blog post here reminded me of a script I’ve been meaning to tidy up and share. This script is used for bulk adding SMTP addresses to Office 365 mailboxes for a new SMTP domain.

This scenario applies to cloud-only Exchange Online scenarios. If you have an on-premises Exchange organization, or are in a Hybrid configuration, or otherwise are using using directory synchronization then this script should not be used, and instead you should use email address policies to make the changes.

The reason I’m sharing my own script instead of just pointing you at Tim’s (which seems fine) or any of the other code samples out there for this task (of which there are many) is that I wanted a script that had a few extra controls, and also one that wrote a log file so I could see what changes are made to the mailboxes it touches.

Here’s how it works. First of all, the script must be run from a PowerShell session that has already been connected to Exchange Online. Use my Connect-EXOnline function for this if you have not already got your own script or function for it.

Next, if you try to add SMTP addresses for a domain name that is not already configured as an accepted domain for your Office 365 tenant, the script will throw an error.

PS C:\Scripts> .\Add-SMTPAddresses.ps1 -Domain office365bootcamp.com
The operation couldn't be performed because object 'office365bootcamp.com' couldn't be found on
'HKXPR04A001DC06.APCPR04A001.prod.outlook.com'.
    + CategoryInfo          : NotSpecified: (:) [Get-AcceptedDomain], ManagementObjectNotFoundException
    + FullyQualifiedErrorId : [Server=SIXPR04MB048,RequestId=f8357ccc-bb99-46e4-b9d9-dda2207d7b28,TimeStamp=14/05/2015
    1:10:13 PM] [FailureCategory=Cmdlet-ManagementObjectNotFoundException] BE34E051,Microsoft.Exchange.Management.Sys
  temConfigurationTasks.GetAcceptedDomain
    + PSComputerName        : pod51055psh.outlook.com

There are three parameters used with the script:

• Domain – the domain name you wish to add (note: new email addresses are added as alias@domain)
• MakePrimary – specifies that the new address should be added as the primary email address. Otherwise the new address is added as a secondary email address by default.
• Commit – specifies that you want to commit the changes. Without this switch the script will not make any changes, but will still log the changes that would have been made to the log file so you can evaluate the impact of the script.

Here’s a few examples.

.\Add-SMTPAddresses.ps1 -Domain office365bootcamp.com

This will perform a test pass for adding the new alias@office365bootcamp.com as a secondary email address to all mailboxes. Use the log file to evaluate the outcome before you re-run with the -Commit switch.

.\Add-SMTPAddresses.ps1 -Domain office365bootcamp.com -MakePrimary

This will perform a test pass for adding the new alias@office365bootcamp.com as a primary email address to all mailboxes. Use the log file to evaluate the outcome before you re-run with the -Commit switch.

.\Add-SMTPAddresses.ps1 -Domain office365bootcamp.com -MakePrimary -Commit

This will add the new alias@office365bootcamp.com as a primary email address to all mailboxes.

The log file records the existing email addresses for the mailboxes, the email address that is being added, and then the full set of email addresses being committed to the mailbox (or not, if the -Commit switch wasn’t specified).

Important Note: You should always test PowerShell scripts before you run them against your production systems. If you do not have a test Office 365 tenant available and want to test this script against a single mailbox you can simply modify this Get-Mailbox command in the script.

#Get the list of mailboxes in the Office 365 tenant
$Mailboxes = @(Get-Mailbox -ResultSize Unlimited)

For example, this will make the script only run against the “Vik.Kirby” mailbox.

#Get the list of mailboxes in the Office 365 tenant
$Mailboxes = @(Get-Mailbox Vik.Kirby)

Add-SMTPAddresses.ps1 can be downloaded from the TechNet Script Gallery or Github. If you have any feedback or issues please leave a comment below or raise an issue on Github.

This article Add-SMTPAddresses.ps1 – Bulk Add SMTP Addresses to Office 365 Mailbox Users is © 2015 ExchangeServerPro.com

Get more Exchange Server tips at ExchangeServerPro.com