How to Execute Bulk Updates of Primary SMTP Address for Distribution Lists

Updating Distribution List Proxy Addresses is a Good Example of PowerShell in Action

A question in the Microsoft Technical Community asks how to perform a bulk update of all distribution lists whose primary SMTP address uses the tenant service domain and replace this address with one from a “vanity” domain owned by the tenant. For example, replace onmicrosoft.contoso.com with contoso.com. This sometimes happens when a tenant begins operations and forgets to assign an address from a vanity domain when creating new distribution lists (Figure 1). It can also occur if an organization decides to use a different domain for whatever reason.

Updating primary SMTP addresses for any mail-enabled object is a great example of how PowerShell is so useful to tenant administrators. Let’s figure out what you might do.

Find Distribution Lists to Update

The first step is to extract the set of domains known for the tenant and find the domain marked as the default. We’ll use that domain to create new primary SMTP addresses:

[array]$Domains = Get-AcceptedDomain
$PreferredDomain = $Domains | Where-Object {$_.Default -eq $True} | Select-Object -ExpandProperty DomainName
If (!($PreferredDomain)) { Write-Host "Can't find the default domain" ; break }

You can use any of the accepted domain defined for the tenant, so if you want to use a different domain, amend the script to insert the desired domain in the $PreferredDomain variable.

Find the Target Distribution Lists

Now let’s find the set of distribution lists that use the service domain for their primary SMTP address:

[array]$DLs = Get-DistributionGroup | Where-Object {$_.PrimarySMTPAddress -like "*onmicrosoft.com*"}
If (!($DLs)) {
   Write-Host "No distribution lists use the service domain for their primary SMTP address" ; break
} Else {
   Write-Host ("{0} distribution lists found to update" -f $DLs.count)
}

To check details of the distribution lists, run this command:

$DLs | Format-Table DisplayName, PrimarySMTPAddress

Update the Distribution Lists with a New Primary SMTP Address

If you’re happy to go ahead, this code uses the Set-DistributionGroup cmdlet to update the primary SMTP address for the distribution lists. The code builds the new primary SMTP address for a list from its alias and the preferred domain:

ForEach ($DL in $DLs) {
  $NewSMTPAddress = $DL.Alias + "@" + $PreferredDomain
  Write-Host ("Updating distribution list {0} with new address {1}..." -f $DL.DisplayName, $NewSMTPAddress )
  Set-DistributionGroup -Identity $DL.Alias -PrimarySMTPAddress $NewSMTPAddress
}

Exchange Online keeps all previous SMTP proxy addresses (including the prior primary SMTP address) to make sure that it can correctly handle messages sent to the distribution lists using those addresses. You can see this by running the Get-DistributionGroup cmdlet to examine the email addresses:

Get-DistributionGroup -Identity 'San Francisco Rooms' | Select-Object -ExpandProperty EmailAddresses
SMTP:SanFranciscoRooms@Office365itpros.com
smtp:SanFranciscoRooms@office365itpros.onmicrosoft.com

Alternatively, you can see the proxy addresses by examining the distribution list properties in the Exchange admin center.

The primary SMTP address is only one distribution list proxy address. Like any Exchange Online recipient, a distribution list can have up to 300 proxy addresses (depending on the length of the addresses), so there’s usually plenty of room to store proxy addresses created for different reasons.

Distribution Lists Still Have a Place

Despite Microsoft’s ongoing efforts to persuade customers that Microsoft 365 groups are better than distribution lists, there’s no doubt that these objects still have a place in any tenant. A Microsoft 365 group is a great choice when you want to use Teams or Outlook groups for collaboration, but scenarios still exist where a simple distribution list is the best way to communicate, especially when you want to include external email addresses (guest accounts can also be members of distribution lists).

Here’s a script to report distribution list membership, just in case you’re looking for another project after fixing distribution list proxy addresses and making sure that the right primary SMTP address is in place.

---

Learn about using Exchange Online and the rest of Office 365 by subscribing to the Office 365 for IT Pros eBook. Use our experience to understand what’s important and how best to protect your tenant.