When managing Office 365, especially during domain migrations or hybrid setups, it’s critical to ensure every user has a corresponding @onmicrosoft.com alias.
This alias helps avoid delivery issues and supports fallback routing if needed.

Today, we’ll walk through how to check if users are missing the @onmicrosoft.com alias — and automatically add it if needed.

Let’s dive in.

What This Script Will Do:

• Pull all mailboxes from Microsoft 365.
• Check if their primary email is from your main domain (e.g., yourdomain.com).
• If so, make sure they also have a yourdomain.onmicrosoft.com alias.
• If missing, add the alias automatically.
• Log everything into a clean, auditable table.

# Connect to Exchange Online
Connect-ExchangeOnline -UserPrincipalName youradmin@yourdomain.com

# Define your domains
$primaryDomain = "yourdomain.com"
$onMicrosoftDomain = "yourdomain.onmicrosoft.com"

# Initialize a results array
$results = @()

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

foreach ($user in $users) {
    $userPrincipalName = $user.UserPrincipalName

    # Only process users whose primary address is @yourdomain.com
    if ($userPrimaryAddress = $user.EmailAddresses | Where-Object { $_ -cmatch "^SMTP:.*@$primaryDomain$" }) {

        # Extract the local part (before the @)
        $localPart = ($userPrimaryAddress -replace "SMTP:", "").Split("@")[0]
        $expectedAlias = "$localPart@$onMicrosoftDomain"

        # Check if alias already exists
        $hasAlias = $user.EmailAddresses | Where-Object { $_ -match [regex]::Escape($expectedAlias) }

        if (-not $hasAlias) {
            Write-Host "Adding alias $expectedAlias to $userPrincipalName" -ForegroundColor Yellow

            # Add the missing alias
            Set-Mailbox $user.Identity -EmailAddresses @{add="smtp:$expectedAlias"}

            $results += [PSCustomObject]@{
                UserPrincipalName = $userPrincipalName
                PrimaryEmail      = $userPrimaryAddress
                AddedAlias        = $expectedAlias
                Action            = "Alias Added"
            }
        }
        else {
            $results += [PSCustomObject]@{
                UserPrincipalName = $userPrincipalName
                PrimaryEmail      = $userPrimaryAddress
                AddedAlias        = $expectedAlias
                Action            = "Alias Already Exists"
            }
        }
    }
    else {
        $results += [PSCustomObject]@{
            UserPrincipalName = $userPrincipalName
            PrimaryEmail      = "N/A"
            AddedAlias        = "N/A"
            Action            = "Skipped (Not $primaryDomain)"
        }
    }
}

# Display the results
$results | Format-Table -AutoSize

# Optional: Export results to CSV for auditing
$timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
$results | Export-Csv -Path "AliasUpdateReport_$timestamp.csv" -NoTypeInformation

Script Summary

Pro Tips

• Always test first: Run the script with the Set-Mailbox line commented out if you want a dry run.
• This script only adds aliases — it never modifies the user’s primary email or login.
• The CSV file gives you a full audit trail you can save for compliance purposes.

Safety Features

✅ Only users in your @yourdomain.com are affected.
✅ Existing aliases are never duplicated.
✅ No disruption to user mail flow.

Conclusion

This approach ensures every user has a matching @onmicrosoft.com alias, keeping your environment clean, compliant, and ready for future migrations or backup routing needs.

If you’re managing a hybrid environment, tenant migration, or simply cleaning up your domain setup, this script will save you hours of manual work.