OPATH recipient filtering for Exchange Server 2007

OPATH is basis for the filtering syntax used by PowerShell, and is therefore the filtering syntax used by Exchange 2007. It replaces the complicated syntax of LDAP used in Exchange 2003, and will allow for filters which are easier to create and interpret. For native PowerShell filters, all work is done client-side in the Powershell host. In Exchange 2007, however, various cmdlets provide “server-side” filters using the same syntax as their client-side counterparts. These server-side filters provide higher performance and added scenarios that are specific to Exchange Server.

This blog post will address some techniques to make use of these “added scenarios” that relate specifically to Exchange Server. For instance, we’ll talk about the RecipientFilter “server-side” filter definitions used by Dynamic Distribution Groups, Email Address Policies, Address Lists, and Global Address Lists.

Note that dynamic distribution groups, email address policies, address lists, and global address lists all share approximately the same filtering behavior. They all share the same concept of “precanned” vs “custom” filters, the same filtering properties (“RecipientFilter”, “IncludedRecipients”, etc), and the same RecipientFilter syntax. Therefore, the examples and techniques below are equally useful for any of these other types, not just for dynamic distribution groups.

When creating dynamic distribution groups (DDGs) with Exchange 2007 Exchange Management Console GUI, you will be presented with three basic decisions used for filtering:

  1. From what OrganizationalUnit scope do I want to include recipients
  2. What sort of recipients do I want to include
  3. Are there any additional things I want to filter on


#1 corresponds to the “RecipientContainer” property in the Exchange shell.

#2 corresponds to the “IncludedRecipients” property.

#3 corresponds to the “ConditionalCompany”, “ConditionalStateOrProvince”, “ConditionalDepartment”, or “ConditionalCustomAttribute” properties.

After you’ve created a DDG through the GUI, you can also notice that the RecipientFilterType is set to “Precanned”. These are the most simple sort of RecipientFilter that can be created, and are the only sort that can be created through the GUI. They take the values you’ve provided to IncludedRecipients, ConditionalCompany, ConditionalStateOrProvince, ConditionalDepartment, or ConditionalCustomAttribute# and automatically turn them into a RecipientFilter for you. We believe the filters available as Precanned cover the most common RecipientFilter cases used in Exchange 2003.

So, for instance in the GUI you could select to filter starting at the “Domain.com/Users” Organizational Unit, starting with all MailboxUser objects, and then filtering to include only those who have Company defined as “Microsoft”. This is a very common sort of DDG and very easy to do in the GUI.

It’s also very easy to do in the Exchange shell (syntax is roughly the same for New or Set):

   Set-DynamicDistributionGroup AllMicrosoft –RecipientContainer “Domain.com/Users” –IncludedRecipients MailboxUsers –ConditionalCompany “Microsoft” –OrganizationalUnit “Domain.com/Users”

Note for clarification: Although they may both look the same in this example, RecipientContainer and OrganizationalUnit are very different. RecipientContainer defines the root of the OU tree from which recipients will be included in the dynamic distribution group. OrganizationalUnit parameter defines where the new dynamic distribution group will be created in the AD. Note also that the RecipientContainer parameter is available only for dynamic distribution group, and not Email Address Policy nor Address List Recipient Filters.

After this command completes, you can inspect the results of the properties we care about with “Get-DynamicDistributionGroup AllMicrosoft | fl Recipient*,Included*“:

RecipientContainer      : Users,28b69b51-a381-4f50-bf34-a5c976b64d9e
RecipientFilter   : (((RecipientType –eq ‘UserMailbox’) –and (Company –eq ‘Microsoft’)) –and –not(Name –like ‘SystemMailbox{*’) –and –not(Name –like ‘CAS{*’))
RecipientFilterType     : Precanned
IncludedRecipients      : MailboxUsers

Note that you can also see what is the equivalent LDAP filter by inspecting the LdapRecipientFilter property. This is a read-only representation of the LDAP filter. Filters cannot be entered directly with LDAP syntax for Exchange 2007.

Now, what if you want to do something more complicated? Something that is not exposed as a filterable property in the GUI? Well, you can build a custom (ie – not precanned) RecipientFilter!

For example, let’s say you want to use that exact same query we just constructed above, EXCEPT that you want it to be also based on the UMEnabled status of the mailbox. In that case, you would need a custom filter and that means you need to use the RecipientFilter property directly:

   Set-DynamicDistributionGroup AllMicrosoft –RecipientFilter { (((RecipientType –eq ‘UserMailbox’) –and (Company –eq ‘Microsoft’)) –and –not(Name –like ‘SystemMailbox{*’) –and –not(Name –like ‘CAS{*’) –and (UMEnabled –eq $true))}

In this example, you’ve just taken the exact syntax used by the Precanned filter, and then added one extra clause onto the end for the UMEnabled boolean. Simple!

A few more quick examples:

All mailboxes that are on the Server1 server and user in the Dallas office:

   Set-DynamicDistributionGroup AllServer1Dallas –RecipientFilter { ServerName –eq ‘Server1’ –and Office –eq ‘Dallas’ }

All recipients that are in the state of Texas and have OtherTelephone starting with 469:

   Set-DynamicDistributionGroup AllTx469 –RecipientFilter { StateOrProvince –eq ‘TX’ –and OtherTelephone –like ‘469*’ }

All mailboxes that are in the state of Texas and have OtherTelephone starting with 469:

   Set-DynamicDistributionGroup AllTx469 –RecipientFilter { RecipientType –eq ‘UserMailbox’ –and StateOrProvince –eq ‘TX’ –and OtherTelephone –like ‘469*’ }

So, what are some of the syntax basics to be aware of?

  • For Precanned filters, use IncludedRecipients parameter along with the various “Conditional<whatever>” parameters to define the filter
    • IncludedRecipients parameter takes the various recipients types that can be used for precanned filters: None, MailboxUsers, Resources, MailContacts, MailGroups, MailUsers, or AllRecipients.
  • For Custom filters, use “-RecipientFilter {  <some filter> }”   (yes, curly braces around the filter)
  • Powershell uses “-and”, “-or”, and “-not” (yes, with leading hyphen)
  • Some other useful comparison operators: “-eq” (equals), “-ne” (not equal), “-lt” (less than), “-gt” (greater than), “-like” and “-notlike” (wildcard string compare).
  • Almost all of the properties exposed on the various recipient types are available to these custom RecipientFilters. Please let us know if you run across one that you need but cannot access!

Other references: Now that Powershell has released, there are several books available that are fairly useful as a reference. Also, the PowerShell team has a blog: http://blogs.msdn.com/powershell/.

Evan Dodds

Comments (8)
  1. pesospesos says:

    Hi guys, I’m running into a filter/ntfs related problem in my test lab.  We host multiple organizations/domains and to achieve separation we have always created custom GALs, ALs, and OABs for each organization, then broken inheritance on NTFS permissions and allowed only folks in each org access to their own GAL/AL/OAB – according to this walkthrough: http://www.msexchange.org/tutorials/Shared-Hosting-Exchange-2003-Part2.html

    This has worked however in my test lab where I’m migrating this type of setup to Ex2007, I seem to be running into a problem.  The GUI doesn’t let you create GALs, so I had to use the command shell — then I had to use adsiedit to set the NTFS perms on the GAL, AL, and OAB.  Ex2007 also doesn’t seem to allow you to base an OAB off of a GAL like you could in ex2003.  When I test my setup, I am getting the "bookmark is not valid" error — any idea on what may be wrong, or if there is another, better method in ex2007 for setting up separate organizations/domains, please let me know!



  2. pesospesos says:

    p.s. the tutorial is basically a rehashing of kb822940 that seems to have been removed (the english version) but is still available in other languages…  I found the english version duplicated here: http://www.administrator.de/Globales_Adressbuch_deaktivieren%3F.html

    How do we achieve this same goal in Exchange 2007?



  3. Anonymous says:

    If you are not familiar with what OPATH is, then you must read these two blogs when you are done reading

  4. Anonymous says:

    I have previously listed the progress we’ve been making in posting ITPro focused Systems Management blog

  5. Neil says:

    Don’t create an OAB from a GAL object if you’re hosting.  The OAB will use the system GAL rather than your GAL object.  Create a second address list object and use that for your OAB.

  6. Anonymous says:

    As discussed in this earlier blog post on OPATH Filters, Exchange 2007 uses a new style of filter syntax…

  7. Anonymous says:

    After installing Exchange 2007 into your existing Exchange organization, the address lists and recipient…

  8. Anonymous says:

    Since I’ve posted a number of times about OPATH filters for Exchange 2007 and RecipientFilter parameter

Comments are closed.