Set Primary Email Address for Office 365 Users using Powershell

In this post, I am going to share Powershell commands to add email alias and set the new alias as the primary email address for Office 365 users. We can use the Set-Mailbox command to add new email alias, remove an old email address and set primary email address.

Note: Before proceed, Connect Exchange Online Remote Powershell.

Add new Email Alias and set as a Primary Email Address

The below command adds the new alias in the EmailAddresses list and sets it as PrimarySmtpAddress. Replace the parameter “username” with Name or UserPrincipalName of the mailbox user.

Set-Mailbox 'username' -WindowsEmailAddress '[email protected]'

Remove old Email Alias

The above command just adds the new email address and it will not remove the existing email, the old email address still works as a proxy address for the primary email address, you may want to remove existing email once you confirmed the new email works fine. You can remove the existing email alias by running the below command.

Set-Mailbox 'username' -EmailAddresses @{Remove='[email protected]'}

Add new Email Alias as Proxy Address

In some cases, you may want to add a new email address for an Office 365 user without affecting the user’s existing primary email address, in this case, you can add the new alias in the EmailAddresses list by running the below command.

Set-Mailbox 'username' -EmailAddresses @{Add='[email protected]'}

Set Primary Email Address for Bulk O365 Users from CSV

In some scenarios, we may be required to add email alias for multiple mailbox users in bulk by importing user details from CSV file. Consider the CSV file Office365Users.csv which contains every users` UPN (or Name) and new email address in each row with the column headers UserPrincipalName and NewEmailAddress.

Import-Csv 'C:\Office365Users.csv' | ForEach-Object {
Set-Mailbox $_."UserPrincipalName" -WindowsEmailAddress $_."NewEmailAddress"
}

Change UserPrincipalName to match with Primary Email Address

In Office 365 cloud, users need to use their UPN (UserPrincipalName) as login name to sign-in to any Office 365 apps, changing user’s WindowsEmailAddress (or PrimarySmtpAddress) will not change UPN of the users, so we may be required to update UPN while setting new email address to avoid confusions for end-users when they login-in to Office 365 apps. The Set-Mailbox command includes the parameter MicrosoftOnlineServicesID, this is the equivalent property of UPN which exists in the mailbox’s associated Azure AD user object, we can set the new email address in this attribute to update UPN of the user.

Set-Mailbox 'username' -WindowsEmailAddress '[email protected]' -MicrosoftOnlineServicesID '[email protected]'

The above command throws the warning message: WARNING: UserPrincipalName “[email protected]” should be same as WindowsLiveID “[email protected]”, UserPrincipalName should remain as “[email protected]”. Ignore this warning message and the UPN will be updated in a few minutes.

Set UPN and Primary Email Address for bulk mailbox users:

The below commands import mailbox users` names and email alias from CSV file and set the new mail address as PrimarySmtpAddress and UserPrincipalName.

Import-Csv 'C:\Office365Users.csv' | ForEach-Object {
Set-Mailbox $_."UserPrincipalName" -WindowsEmailAddress $_."NewEmailAddress" -MicrosoftOnlineServicesID $_."NewEmailAddress"
}