Use PowerShell to Change a Microsoft 365 Alias Address to the Primary Email Address

The organization is going to use a new primary SMTP address. They already have that new address set as an alias address for all the mailboxes. Now, they want to swap it with the primary SMTP address. If there are other alias addresses, they need to be left untouched. In this article, you will learn how to change the alias address to the primary SMTP address in Microsoft 365 with PowerShell.

Introduction

The Set-M365PrimaryAddress.ps1 PowerShell script works for Exchange Online (Microsoft 365). If you like to do the same but for Exchange on-premises or Exchange Hybrid environment, then read the article Change alias address to primary SMTP address with PowerShell.

Before you start

What if there is no alias address already set for every mailbox? The best is to go through the article Bulk add secondary SMTP address with PowerShell.

Once you have verified that the alias address is set for all the mailboxes, run the Set-M365PrimaryAddress.ps1 PowerShell script from this article to swap the alias address with the primary SMTP address.

Suppose you are done and want to remove the old primary SMTP address that is now an alias address, you can go through the article Bulk remove secondary SMTP address with PowerShell.

It’s always better to do this in stages than with one script that does it all immediately so you are sure everything is correctly set.

Prepare set Microsoft 365 Primary SMTP address PowerShell script

Download the Set-M365PrimaryAddress.ps1 PowerShell script or copy and paste the code below into Notepad. Give it the name Set-M365PrimaryAddress.ps1 and place it in the C:\scripts folder. Create a Scripts folder if you don’t have one.

<#
    .SYNOPSIS
    Set-M365PrimaryAddress.ps1

    .DESCRIPTION
    Get the secondary (alias) address from a specified domain and set it as the primary SMTP address
    for all mailbox users in Exchange Online (Microsoft 365). If there is no alias address set with
    the specified domain, it will skip the user and display a message. The primary SMTP address will
    become an alias address and all the secondary email address will remain.

    .LINK
    www.alitajran.com/change-microsoft-365-alias-address-to-primary-smtp-address/

    .NOTES
    Written by: ALI TAJRAN
    Website:    alitajran.com
    X:          x.com/alitajran
    LinkedIn:   linkedin.com/in/alitajran

    .CHANGELOG
    V1.00, 09/01/2024 - Initial version
#>

param (
    [Parameter(Mandatory = $true)]
    [string]$DomainName,
    [switch]$WhatIf
)

# Output will be added to C:\temp folder. Open the log with a text editor.
Start-Transcript -Path C:\temp\Set-M365Primary-SMTP-Address.log -Append

# Specify the domain to set as primary SMTP
$primarySMTPDomain = "@" + $DomainName

# Get all mailbox users
$users = Get-Mailbox -ResultSize Unlimited

foreach ($user in $users) {
    $currentPrimarySMTP = $user.PrimarySmtpAddress.ToString()
    $allEmailAddresses = $user.EmailAddresses
    $aliasAddresses = $allEmailAddresses | Where-Object { $_ -clike "smtp:*$primarySMTPDomain" }

    # Check if the current primary SMTP address ends with the specified domain
    if ($currentPrimarySMTP -like "*$primarySMTPDomain") {
        Write-Host "Skipping $($user.DisplayName) - Primary SMTP already ends with $primarySMTPDomain" -ForegroundColor Yellow
    }
    elseif ($aliasAddresses.Count -eq 1) {
        $newPrimarySMTP = $aliasAddresses -replace "smtp:", "SMTP:"
        Write-Host "Updating primary SMTP for $($user.DisplayName) to $newPrimarySMTP" -ForegroundColor Green

        # Combine new primary with other addresses (keeping all existing addresses)
        $updatedAddresses = @($newPrimarySMTP) + ($allEmailAddresses -replace "SMTP:", "smtp:" | Where-Object { $_ -ne $newPrimarySMTP })

        # Set the new primary SMTP address
        if ($WhatIf) {
            Set-Mailbox -Identity $user -EmailAddresses $updatedAddresses -WhatIf
        }
        else {
            Set-Mailbox -Identity $user -EmailAddresses $updatedAddresses
        }
    }
    elseif ($aliasAddresses.Count -eq 0) {
        Write-Host "No alias address found for $($user.DisplayName) - Primary SMTP not updated" -ForegroundColor Cyan
    }
    else {
        Write-Host "Multiple alias addresses found for $($user.DisplayName) - Primary SMTP not updated" -ForegroundColor Red
    }
}

Stop-Transcript

Bulk set Microsoft 365 Primary SMTP address PowerShell script

The script works for Exchange Online in a Microsoft 365 environment. Run PowerShell as administrator and Connect to Exchange Online PowerShell.

Connect-ExchangeOnline

Go to the script path and run the Set-M365PrimaryAddress.ps1 script. The script will go through all the mailboxes in the Exchange Online organization.

C:\scripts\.\Set-M365PrimaryAddress.ps1 -DomainName "exoip.nl" -WhatIf

Run the script without the -WhatIf parameter.

C:\scripts\.\Set-M365PrimaryAddress.ps1 -DomainName "exoip.nl"

If multiple alias addresses for a mailbox exist, it will not apply any changes, and the output will show that information so you can look into it.

In this example, the existing alias address with the domain @exoip.nl will be set in bulk as the primary SMTP address.

Transcript started, output file is C:\temp\Set-M365Primary-SMTP-Address.log
Multiple alias addresses found for Adam Clark - Primary SMTP not updated
No alias address found for ALI TAJRAN - Primary SMTP not updated
Updating primary SMTP for Alison Bell to SMTP:Alison.Bell@exoip.nl
No alias address found for Grace Rees - Primary SMTP not updated
Skipping Jeff Baker - Primary SMTP already ends with @tajran.com
No alias address found for John Maverick - Primary SMTP not updated
No alias address found for Joshua Hunter - Primary SMTP not updated
Updating primary SMTP for Zoë Roberts to SMTP:Zoe.Roberts@exoip.nl
Transcript stopped, output file is C:\temp\Set-M365Primary-SMTP-Address.log

That’s it!

Read more: Find email addresses with PowerShell »

Conclusion

You learned how to bulk set alias address as primary SMTP address in Microsoft 365 with PowerShell. First, download the Set-M365PrimaryAddress PowerShell script. Then, add the domain in the command you want it to search for in the mailbox alias addresses. At last, run the script. Remember to test first with the -WhatIf parameter.

Did you enjoy this article? You may also like Send as Alias from Microsoft Outlook mobile app (iOS and Android). Don’t forget to follow us and share this article.