How to Create Exchange Dynamic Distribution List with Custom Recipient Filters

Build Filters Against Multiple Azure AD Properties

A post in the Microsoft Technical Community looked for help building a dynamic distribution list based on multiple Azure AD properties. Our esteemed technical editor, Vasil Michev, stepped in to help and involved me. I pointed out that this topic is covered in Chapter 6 of the Office 365 for IT Pros eBook (easy to miss in 1,250 pages) but admitted that the question was interesting.

Dynamic distribution lists are an undervalued part of Exchange Online. The concept has existed since Exchange 2003 introduced the query-based distribution group, or QDG. The current implementation came in Exchange 2007. In both cases, a query is resolved against the directory to identify the set of recipients for a message. The list is dynamic because the set of recipients will change based on the contents of the directory.

Precanned and Custom Recipient Filters

The Exchange admin center (EAC) GUI is designed to make it easy to create the queries for dynamic distribution lists. It does this by limiting the set of properties available for queries, like department and city. The queries generated by the EAC are called precanned and are stored as the recipient filter for the list.

Custom queries can use a much wider set of properties. The downside is that you must build the queries by hand and update dynamic distribution lists with PowerShell. That might seem hard, but it’s really not.

Excluding Some Mailboxes

In this instance, the need is to have a dynamic distribution list to address mailboxes owned by people with a specific job title but exclude any whose Azure AD accounts are blocked for sign-in. Figure 1 shows the account of architect Ben James. The account is blocked.

Details of a blocked Azure AD account
Figure 1: Details of a blocked Azure AD account

When an Azure AD account is blocked, Exchange synchronizes the status and updates the ExchangeUserAccountControl mailbox property. To find the set of recipients who have architect in their job title and can still sign in, we can build a recipient filter which checks the Title and ExchangeUserAccountControl properties. Because people might have prefixes to indicate the seniority of their architect status, we need to include some variants of the job title. Exchange only supports wildcards for filters at the end of a string (“architect*”) instead of the start (“*architect”), which would be more useful in this case.

Building and Testing a Recipient Filter with PowerShell

Here’s what a custom filter to check for a job title and account blocked status looks like:

$Filter = "((Title -eq 'Architect') -or (Title -eq 'Senior Architect') -or (Title -eq 'Principal Architect') -and (ExchangeUserAccountControl -ne 'AccountDisabled'))"

To know if the filter works, we can use the Get-Recipient cmdlet. Get-Recipient accepts the filter defined in the $Filter variable and returns what it finds in the directory. This is exactly what will be returned as the set of recipients when the Exchange transport service resolves the query.

Get-Recipient -RecipientPreviewFilter $Filter | ft displayname, title

DisplayName                   Title
-----------                   -----
Ben James                     Architect
Eoin Redmond (Ireland)        Architect
James Joyce                   Principal Architect
Tony Redmond                  Principal Architect
Vasil Michev (Technical Guru) Senior Architect

It’s important to test any filter before using it with a dynamic distribution list. If the query generated by the filter fails to resolve and return any recipients, any message sent to the list goes into a black hole. Exchange won’t generate a non-delivery notification because the address used for the message is valid (the list); the problem lies with what happens when the query is run against the directory.

Creating a Dynamic Distribution List with PowerShell

After you’re sure that the filter returns the correct set of recipients, you can create a dynamic distribution list using the filter. For example:

New-DynamicDistributionGroup -Name "Architects" -DisplayName "System and Engineering Architects" -Alias AllArchitects -PrimarySmtpAddress -RecipientFilter $Filter
Set-DynamicDistributionGroup -Identity AllArchitects -ManagedBy Tony.Redmond -MailTip "Distribution List for anyone with Architect in the job title"

The second command is to add an owner for the dynamic distribution list and to assign a mail tip for clients like Outlook to display when people address email to the list.

EAC Blocks Edits of Custom Recipient Filters

Any further adjustments to the recipient filter can only be made with PowerShell. If you look at a custom recipient filter with the Exchange admin center, it’s blocked for edit (Figure 2).

EAC stops any attempt to update a custom recipient filter for a dynamic distribution list
Figure 2: EAC stops any attempt to update a custom recipient filter for a dynamic distribution list

As for Ben James, when his Azure AD account is reenabled for sign-in, he’ll start to receive messages sent to the dynamic distribution list again, which is exactly what we want.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.