How to Move Distribution List Membership from One Mailbox to Another

A reader asks what’s the best way to transfer the membership of distribution lists from one user account to another? If this is a one-off operation involving just a few DLs, the right answer is to add the new account to the DLs using your preferred administrative interface (Microsoft 365 admin center, Exchange admin center, or PowerShell).

Automating Distribution List Updates

Handling a few adjustments to distribution list membership through a GUI is acceptable. But if the membership of 30 or 40 distribution lists must be adjusted, which sometimes happens when people change jobs, it’s better to automate the process (if only to avoid boredom).

The capabilities of Exchange Online PowerShell make this task very straightforward. The basic approach is:

• Find the source mailbox (check it exists, etc.).
• Find the target mailbox.
• Find the set of distribution lists the source mailbox is a member of. If the mailbox doesn’t belong to any distribution lists, say so and exit.
• Display the set of distribution lists to be transferred and prompt for approval to proceed.
• If yes, go ahead and add the target mailbox to the membership of each of the distribution lists in the set. Optionally, remove the source mailbox from the same distribution lists.

Here’s some code to illustrate the principle.

$SM = Read-Host "Enter name of source mailbox"
$SourceMailbox = (Get-ExoMailbox -Identity $SM -ErrorAction SilentlyContinue -RecipientTypeDetails UserMailbox)
If (!($SourceMailbox)) { Write-Host "Unable to find mailbox for" $SM " - exiting"; break }
$TM = Read-Host "Enter name of target mailbox"
$TargetMailbox = (Get-ExoMailbox -Identity $TM -ErrorAction SilentlyContinue -RecipientTypeDetails UserMailbox)
If (!($TargetMailbox)) { Write-Host "Unable to find mailbox for" $TM " - exiting"; break }
$DN = $SourceMailbox.DistinguishedName
$NewDN = $TargetMailbox.DistinguishedName
[array]$DLs = (Get-DistributionGroup -ResultSize Unlimited -Filter "Members -eq '$DN'" | Select DisplayName, Notes, ExternalDirectoryObjectId, ManagedBy, PrimarySmtpAddress)

If ($DLs.Count -eq 0) { Write-Host "Sorry, but" $SourceMailbox.DisplayName "isn't a member of any distribution groups - exiting" ; break }

CLS
$DLs | Format-Table DisplayName, PrimarySMTPaddress -AutoSize
$PromptTitle = 'Transfer membership of Distribution Lists'

$PromptMessage = 'Please confirm whether to go ahead and transfer membership of ' + $DLS.Count + ' distribution lists from ' + $SM  + ' to ' + $TM
$yes = New-Object System.Management.Automation.Host.ChoiceDescription "&yes", 'yes?'
$no = New-Object System.Management.Automation.Host.ChoiceDescription "&no", 'no?'
$cancel = New-Object System.Management.Automation.Host.ChoiceDescription "&cancel", 'Exit'
$PromptOptions = [System.Management.Automation.Host.ChoiceDescription[]]($yes, $no, $cancel)
$PromptDecision = $host.ui.PromptForChoice($PromptTitle, $PromptMessage, $PromptOptions, 0) 

If ($PromptDecision -eq 0) { # Yes
  ForEach ($DL in $DLs) {
     Write-Host "Adding user" $TargetMailbox.DisplayName "to DL" $DL.DisplayName "and removing" $SourceMailbox.DisplayName
     Add-DistributionGroupMember -Identity $DL.ExternalDirectoryObjectID -BypassSecurityGroupManagerCheck -Member $TargetMailbox.PrimarySmtpAddress -ErrorAction SilentlyContinue
     Remove-DistributionGroupMember -Identity $DL.ExternalDirectoryObjectId -Confirm:$False -Member $SourceMailbox.PrimarySmtpAddress -BypassSecurityGroupManagerCheck -ErrorAction SilentlyContinue
  } # End Foreach
} # End if

[array]$NewDLs = (Get-DistributionGroup -ResultSize Unlimited -Filter "Members -eq '$NewDN'" | Select DisplayName, Notes, ExternalDirectoryObjectId, ManagedBy, PrimarySmtpAddress)
Write-Host " "
Write-Host ("All done. {0} is now a member of {1} distribution lists." -f $TargetMailbox.DisplayName, $NewDLs.Count)
$NewDLs | Format-Table DisplayName, PrimarySmtpAddress

There are many enhancements you could make to the code, including checking if the source mailbox is the owner of any of the distribution lists and if their removal leaves the distribution list in an ownerless state (this isn’t good). The code is written for Exchange Online but should work on-premises with a few adjustments (like switching Get-Mailbox for Get-ExoMailbox and using a different property for the distribution list identity).

Handling Dynamic Distribution List Membership

Transferring membership of dynamic distribution lists is more difficult. Dynamic distribution lists depend on a query (filter) executed against the Exchange Directory to resolve the set of recipients. Filters can be precanned, meaning that they execute against a set of well-known object properties like the department or city. Alternatively, the list owner or maintainer can create a custom filter with PowerShell to query against any property available for mail-enabled objects. Custom filters can be an excellent way to find the

Both precanned and custom filters depend on directory data. It therefore follows that to transfer membership from one mailbox to another, you need to understand the properties used by the filter and then adjust the properties of the target mailbox in the directory so that the filter includes the target mailbox in its result set when it runs. It’s possible to update directory properties with PowerShell to make sure that mailboxes are found by precanned or simple custom filters, but this becomes more difficult for complex custom filters. Given the number of dynamic distribution lists which are probably involved in moving membership from one mailbox to another, it’s probably best to make the changes manually.

And the Graph?

It would also be possible to transfer membership of distribution lists using the Microsoft Graph Groups API. However, this is an example of a situation where plain and simple PowerShell is all that’s needed. You won’t speed up the updates to any significant degree and will spend longer writing the code. That’s not a good trade-off, so stick with PowerShell and contemplate how easy it is to automate operations like this with just a few commands.

---

Learn more about how Office 365 really works on an ongoing basis by subscribing to the Office 365 for IT Pros eBook. Our monthly updates keep subscribers informed about what’s important across the Office 365 ecosystem.