Office 365: Bulk update email addresses

In Office 365 there may be a need to perform a bulk update to email addresses across accounts.  The accepted domain may need updating as new domains are added or the email address prefix may be changing. 

In an on-premises environment the bulk modification of email addresses can be performed through adjustments in the recipient update service and recipient policies.  When directory synchronization is used with Office 365 this is still a viable method – as proxy addresses is sourced on premises.  (Note:  If no on premises server exists proxy addresses must then be manually modified in the Active Directory).  As the proxy addresses are changed on premises the directory synchronization process will replication the changes into Office 365.

If mailbox and user accounts are created directly in Office 365 then administrators must adjust the email addresses in Office 365.  Within Office 365 there is no recipient update service or recipient policies that can be adjusted to perform these modifications in bulk.  Each email address modification must occur directly on the user.  If a small number of users are involved in the change then using the Exchange portal may be the easiest method to process the change.  When the change must occur over a bulk of users then it may be helpful to script these changes.

In this scripting example the desire is to change the email address from alias@acceptedDomain.com to firstInitial.lastName@acceptedDomain.com.  To begin the list of mailboxes that require the change need to be parsed into a variable.  To gather the recipients we will use the get-recipient command.  The get-recipient command returns the list of proxy addresses on the users which will be helpful in further script steps.  The command in this example should only return recipients that are mailboxes. 

#Get a list of recipients. Command may be further scoped as necessary to include only a subset of mailboxes.

$recipients=get-recipient –resultSize:UNLIMITED –recipientType:USERMAILBOX

With the recipients extracted we must now iterate through them.  In this iteration we will collect the email addresses off the user into a variable.  We will then construct the new email addresses for the user by first converting the primary proxy address of the user signified with SMTP: to a secondary address signified by smtp:.  The new email address will then be constructed, set as primary, and added to the list of email addresses.  The list of email addresses is then committed to the mailbox.

#Iterate through the list of mailboxes

$recipients | foreach {

#Extract email addresses to a variable

$emailAddress = $_.emailAddresses

#Convert exist primary proxy address to a secondary email address

$newEmailAddress = $emailAddress.replace(“SMTP”,”smtp”)

#Construct the new email address, set it as primary, and add it to the list of existing email addresses.

#The use of SMTP: signifies primary email address.

#Substring is utilized to extract the first initial of the users first name.

$newEmailAddress=$newEmailAddress + (“SMTP:” + ($_.firstName).substring(0,1) + “.” + $_.lastName + “@acceptedDomain.com”)

#Commit the new set of email addresses to the mailbox.

set-mailbox –identity $_.alias –emailAddresses $newEmailAddress

}

When constructing the new email addresses different variations may be utilized.  The current primary SMTP address must always be converted to secondary prior to creating new primary addresses.  For example, if firstName.lastName was the desired email address the following syntax could be used:

$newEmailAddress=$newEmailAddress+ (“SMTP:” + $_.firstName + “.” + $_.lastName + “@acceptedDomain.com”)

The script blocks used here can be combined into a single *.ps1 file. 

A special thanks to Matt Byrd for assisting in the final syntax.