Share via

Create Dynamic Distribution Groups Using Customized Filters

  • Article

Applies to: Office 365 for enterprises, Live@edu

Use customized filters to create dynamic distribution groups when the attributes that you want to use aren't available with precanned filters, or when you want to use wildcard matches. For example, if you create a dynamic distribution group that filters on the Department attribute value "R*" and the Title attribute "Engineer", messages sent to this group are delivered only to user accounts that have those attributes.

To learn how to create dynamic distribution groups using precanned filters, see Create Dynamic Distribution Groups Using Precanned Filters.

You create and modify dynamic distribution groups using Windows PowerShell. A customized filter requires use of OPATH, the filtering syntax used by Windows PowerShell.

Before you begin

To learn how to install and configure Windows PowerShell and connect to the service, see Use Windows PowerShell in Exchange Online.

When you create your customized filter:

  • Use braces { } around the whole OPATH syntax string.

  • Include the hyphen before all operators.

  • Remember these most frequently used operators.

    -and

    -lt (less than)

    -or

    -gt (greater than)

    -not

    -like (string comparison)

    -eq (equals; not case-sensitive)

    -notlike (string comparison)

    -ne (does not equal; not case-sensitive)

    Note   When you use the -like or -notlike operators, you must use a wildcard in the string. For example, Department -like 'Sales*'.

    Note   When you use a wildcard, it can’t be used as the first character. It must follow a text string. For example, Sales* is allowed, but *Sales isn’t allowed.

Use a customized filter to create a new dynamic distribution group

Run the following command:

New-DynamicDistributionGroup -Name <group name> -RecipientFilter {<custom filter attribute conditions>}

Example Here's a command that uses a customized filter to create a new dynamic distribution group named "Washington Management Team". A message sent to this dynamic distribution group will be delivered to all users in Washington State whose titles start with "Director" or "Manager".

To create a new dynamic distribution group by using a customized filter, run the following command:

New-DynamicDistributionGroup -Name "Washington Management Team" -RecipientFilter {(RecipientType -eq 'UserMailbox') -and (Title -like 'Director*' -or Title -like 'Manager*') -and (StateOrProvince -eq 'WA')}

Did you know?

Here are some of the more interesting recipient properties that you can use with customized filters. Note that this table doesn't include every available property.

Property name Available for cloud-based recipient types Value type Wildcard character accepted? * Property visible in the Exchange Control Panel

City
  • Account
  • Mail contact
  • Mail user

String

Yes

Yes

Company
  • Account
  • Mail contact
  • Mail user

String

Yes

Yes

CountryOrRegion
  • Account
  • Mail contact
  • Mail user

String   The string is based on the ISO 3166 two-letter country code or the name of the country or region. You can find the valid values for the CountryOrRegion parameter from the Country/Region field in the Contact Information section of the account properties in the Exchange Control Panel.

No

Yes

CustomAttributeN where N is an integer from 1 through 15.
  • Account
  • Distribution group
  • Dynamic distribution group
  • Mail contact
  • Mail user

String

Yes

No

Department
  • Account
  • Mail contact
  • Mail user

String

Yes

Yes

ExtensionCustomAttributeN where N is an integer from 1 through 5.
  • Account
  • Distribution group
  • Dynamic distribution group
  • Mail contact
  • Mail user

Multi-valued string; each ExtensionCustomAttributeN can hold up to 1,300 values.

Yes

No

Manager
  • Account
  • Mail contact
  • Mail user

String

Yes

Yes

Notes
  • Account
  • Dynamic distribution group
  • Mail contact
  • Mail user

String

Yes

Yes

Office
  • Account
  • Mail contact
  • Mail user

String

No

Yes

PostalCode
  • Account
  • Mail contact
  • Mail user

String

Yes

Yes

RecipientType

All recipient types
  • DynamicDistributionGroup
  • MailContact
  • MailUniversalDistributionGroup
  • MailUser
  • UserMailbox

No

Not applicable

StateOrProvince
  • Account
  • Mail contact
  • Mail user

String

Yes

Yes

StreetAddress
  • Account
  • Mail contact
  • Mail user

String

No

Yes

Title
  • Account
  • Mail contact
  • Mail user

String

No

Yes

* As previously mentioned, a wildcard can’t be used as the first character. It must follow a text string.

Add recipient filters to a dynamic distribution group

When you use dynamic distribution groups to send e-mail messages, you may unintentionally send messages to system mailboxes. Some system mailboxes reject e-mail sent directly to them, which generates a non-delivery report (NDR). To prevent messages from being sent to system mailboxes, you can add additional recipient filters to your dynamic distribution groups.

Display default recipient filters

Before you add recipient filters, you can run the following command to display the additional recipient filters that Exchange automatically applies to all dynamic distribution groups to help prevent message delivery to system mailboxes:

Get-DynamicDistributionGroup <name> | Format-List Name,RecipientFilter

For example, the output of this command displays the following information about the "Washington Management Team" dynamic distribution group created in the previous example:

Name: Washington Management Team
RecipientFilter: ((((((RecipientType -eq 'UserMailbox') -and (((Title -like 'Director*') -or (Title -like 'Manager*'))))) -and (StateOrProvince -eq 'WA'))) -and (-not(Name -like 'SystemMailbox{*')) -and (-not(Name -like 'CAS{*')) -and (-not(RecipientTypeDetailsValue -eq 'MailboxPlan')) -and (-not(RecipientTypeDetailsValue -eq 'ArbitrationMailbox')))

Because of the default recipient filters that were automatically added, messages sent to this dynamic distribution group won't be sent to:

  • Mailboxes that have "SystemMailbox" or "CAS_" in the value of Name
  • Mailbox plans
  • Arbitration mailboxes

Add more recipient filters to help avoid NDRs

Here's a command to add additional recipient filters to the "Washington Management Team" dynamic distribution group that aren't included in the default recipient filters:

Set-DynamicDistributionGroup "Washington Management Team" -RecipientFilter {((RecipientType -eq 'UserMailbox') -and (Title -like 'Director*' -or Title -like 'Manager*') -and (StateOrProvince -eq 'WA') -and (Alias -ne $null) -and -not (Name -like "FederatedEmail*"))}

This command adds additional filters so that messages won't be sent to:

  • Mailboxes that don't have a value for Alias
  • Mailboxes that have "FederatedEmail" in the value of Name

Important   When you add filters to an existing dynamic distribution, be sure to include the existing recipient filters. Why? The Set-DynamicDistributionGroup cmdlet replaces the existing recipient filters with the value you specify. Also, you don't need to specify the default recipient filters. Exchange will add these filters automatically.