image
Dave Herrell
Dave Herrell - Blog - IT Toolbox - PowerShell Banner
Active Directory, Azure, Entra ID (Azure AD), Groups, MS Exchange, MS365, PowerShell Basics, Users

PowerShell: How to Add an Alias to Every Users Mailbox and Groups in Microsoft 365

Need to add a new alias domain to your Microsoft 365 users and groups? This guide walks through how to scan all mailboxes, distribution groups, and mail-enabled security groups for a specific primary email domain and then automatically add a matching alias with a new domain alias using PowerShell in Azure Cloud Shell.

Scenario

Let’s say your organization has purchased a cool domain name, or has merged with another company with a new domain. You’re tasked with:

  • Identify all users and groups whose primary email is on @example.com

  • Automatically generate a matching alias in the @example.us format

  • Avoid duplicating aliases that already exist

Here’s how to do it safely and efficiently without needing to install any PowerShell modules locally. 

Prerequisites

You’ll need:

  • Microsoft 365 admin permissions

  • Exchange Online PowerShell access (included in Azure Cloud Shell)

  • The @example.us domain must be already verified and added in Microsoft 365

 

User Email Alias Script (Only updates users and shared mailboxes).

Open Azure Cloud Shell (PowerShell mode) and paste the entire script below:

				
					# Let make sure you're connected to Exchange Online
# Connect-ExchangeOnline

# Get all user mailboxes
$mailboxes = Get-Mailbox -ResultSize Unlimited

foreach ($mb in $mailboxes) {
    # Get the primary SMTP address
    $primary = $mb.PrimarySmtpAddress

    # Check if primary address ends with '@example
    if ($primary -like "*@example.com") {
        # Extract the local part (before the @)
        $localPart = $primary.ToString().Split("@")[0]

        # Construct the new alias
        $newAlias = "$localPart@example.us"

        # Check if alias already exists
        if ($mb.EmailAddresses -notcontains "smtp:$newAlias") {
            Write-Host "Adding alias $newAlias to $($mb.DisplayName)"

            # Add alias
            Set-Mailbox -Identity $mb.Identity -EmailAddresses @{add="smtp:$newAlias"}
        } else {
            Write-Host "$newAlias already exists for $($mb.DisplayName)"
        }
    }
}

Distribution Email Alias Script (Only updates distribution and teams addresses). 

Open Azure Cloud Shell (PowerShell mode) and paste the entire script below:

				
					# Connect to Exchange Online
Connect-ExchangeOnline

# Define the custom alias function
function Add-CustomEmailAlias {
    param (
        [string]$Identity,
        [string]$PrimarySmtpAddress,
        [array]$EmailAddresses,
        [string]$Type  # "Mailbox" or "Group"
    )

    if ($PrimarySmtpAddress -like "*@example.com") {
        $localPart = $PrimarySmtpAddress.Split("@")[0]
        $newAlias = "$localPart@example.us"

        if ($EmailAddresses -notcontains "smtp:$newAlias") {
            Write-Host "✅ Adding alias $newAlias to ${Type}: $Identity"

            if ($Type -eq "Mailbox") {
                Set-Mailbox -Identity $Identity -EmailAddresses @{add="smtp:$newAlias"}
            }
            elseif ($Type -eq "Group") {
                Set-DistributionGroup -Identity $Identity -EmailAddresses @{add="smtp:$newAlias"}
            }
        }
        else {
            Write-Host "⚠️ Alias already exists: $newAlias for ${Type}: $Identity"
        }
    }
}

# Process mailboxes
$mailboxes = Get-Mailbox -ResultSize Unlimited
foreach ($mb in $mailboxes) {
    Add-CustomEmailAlias -Identity $mb.Identity `
                         -PrimarySmtpAddress $mb.PrimarySmtpAddress `
                         -EmailAddresses $mb.EmailAddresses `
                         -Type "Mailbox"
}

# Process distribution groups
$distGroups = Get-DistributionGroup -RecipientTypeDetails MailUniversalDistributionGroup -ResultSize Unlimited
foreach ($dg in $distGroups) {
    Add-CustomEmailAlias -Identity $dg.Identity `
                         -PrimarySmtpAddress $dg.PrimarySmtpAddress `
                         -EmailAddresses $dg.EmailAddresses `
                         -Type "Group"
}

# Process mail-enabled security groups
$mailSecGroups = Get-DistributionGroup -RecipientTypeDetails MailUniversalSecurityGroup -ResultSize Unlimited
foreach ($sg in $mailSecGroups) {
    Add-CustomEmailAlias -Identity $sg.Identity `
                         -PrimarySmtpAddress $sg.PrimarySmtpAddress `
                         -EmailAddresses $sg.EmailAddresses `
                         -Type "Group"
}

Update both Distribution and Users Email Alias Script 

Open Azure Cloud Shell (PowerShell mode) and paste the entire script below:

				
					# Connect to Exchange Online
Connect-ExchangeOnline

# Define the custom alias function
function Add-CustomEmailAlias {
    param (
        [string]$Identity,
        [string]$PrimarySmtpAddress,
        [array]$EmailAddresses,
        [string]$Type  # "Mailbox" or "Group"
    )

    if ($PrimarySmtpAddress -like "*@example.com") {
        $localPart = $PrimarySmtpAddress.Split("@")[0]
        $newAlias = "$localPart@example.us"

        if ($EmailAddresses -notcontains "smtp:$newAlias") {
            Write-Host "✅ Adding alias $newAlias to ${Type}: $Identity"

            if ($Type -eq "Mailbox") {
                Set-Mailbox -Identity $Identity -EmailAddresses @{add="smtp:$newAlias"}
            }
            elseif ($Type -eq "Group") {
                Set-DistributionGroup -Identity $Identity -EmailAddresses @{add="smtp:$newAlias"}
            }
        }
        else {
            Write-Host "⚠️ Alias already exists: $newAlias for ${Type}: $Identity"
        }
    }
}

#Process mailboxes
$mailboxes = Get-Mailbox -ResultSize Unlimited
foreach ($mb in $mailboxes) {
    Add-CustomEmailAlias -Identity $mb.Identity `
                         -PrimarySmtpAddress $mb.PrimarySmtpAddress `
                         -EmailAddresses $mb.EmailAddresses `
                         -Type "Mailbox"
}

#Process distribution groups
$distGroups = Get-DistributionGroup -RecipientTypeDetails MailUniversalDistributionGroup -ResultSize Unlimited
foreach ($dg in $distGroups) {
    Add-CustomEmailAlias -Identity $dg.Identity `
                         -PrimarySmtpAddress $dg.PrimarySmtpAddress `
                         -EmailAddresses $dg.EmailAddresses `
                         -Type "Group"
}

#Process mail-enabled security groups
$mailSecGroups = Get-DistributionGroup -RecipientTypeDetails MailUniversalSecurityGroup -ResultSize Unlimited
foreach ($sg in $mailSecGroups) {
    Add-CustomEmailAlias -Identity $sg.Identity `
                         -PrimarySmtpAddress $sg.PrimarySmtpAddress `
                         -EmailAddresses $sg.EmailAddresses `
                         -Type "Group"
}
What You’ll See

  • ✅ messages for newly added aliases

  • ⚠️ warnings for aliases that already exist

  • No changes made to shared mailboxes or resource mailboxes (but it’s easy to extend, check the info below)

 
Want to add Shared mailboxes?

  • Want to include shared mailboxes too? Just run Get-Mailbox -RecipientTypeDetails SharedMailbox and loop through them.

  • Need a CSV log of all changes? Add Export-Csv to the Write-Host lines or append to a file.

  • To run it again safely, the script checks for existing aliases first.

Whether you need to rebrand, expand, or configure region-specific aliases, this PowerShell script offers a cloud-native, repeatable solution for batch-updating Microsoft 365 user and group addresses.

Hope you find this helpful!

Pull this from my GitHub Teams Repo
Pull this from my Bitbucket Teams Repo