Transport Rule Predicates

 

Applies to: Exchange Server 2010 SP3, Exchange Server 2010 SP2

In Microsoft Exchange Server 2010, predicates are used to create conditions and exceptions in a transport rule. Transport rules can be applied to e-mail messages routed through Hub Transport and Edge Transport servers. Some predicates are available on both transport server roles, and some are exclusive to just one transport server role.

Contents

Predicates and Predicate Properties

Predicates Available on Hub Transport servers

Predicates Available on Edge Transport servers

Predicate Properties

Predicates and Predicate Properties

Transport rule conditions and exceptions consist of one or more predicates. Predicates instruct the Transport Rules agent on a Hub Transport server (or the Edge Rules agent on an Edge Transport server) to examine a specific part of an e-mail message, such as sender, recipients, subject, other message headers, and message body, to determine whether the rule should be applied to that message. As such, predicates act as building blocks for conditions and exceptions.

To determine whether a transport rule should be applied to a message, most predicates have one or more properties for which you must specify a value. The Transport Rules agent inspects message properties for specified values. For example, the HasClassification predicate requires that you specify one or more message classifications for the classification property. Some predicates don't have properties. For example, the HasNoClassification predicate simply inspects whether a message has a classification, and therefore doesn't require any values.

To assign a value to a predicate, you must determine the predicate property or properties in the case of predicates that require more than one property. In the Exchange Management Console (EMC), you can specify predicate values in the Edit the rule description by clicking an underlined value box of the New Transport Rule or Edit Transport Rule wizards. In the Exchange Management Shell the properties are available as parameters of the New-TransportRule and Set-TransportRule cmdlets. Property values are specified after the property name.

Note

In Exchange 2010, you don't need to instantiate predicates and actions by using the Get-TransportRulePredicate and Get-TransportRuleAction cmdlets. These cmdlets only allow you to list the predicates and actions available for use on the Hub Transport and Edge Transport servers on which the cmdlets are executed. The New-TransportRule and Set-TransportRule cmdlets have all the predicates and actions available as parameters, allowing you to create or modify a transport rule using a single command.

Because some predicates examine specific fields within an e-mail message (such as the message header fields), you must set two predicate properties. When you use a predicate to inspect message headers, one predicate property specifies the header to examine, such as To, From, Received, or Content-Type. You must also specify a value for the second property. Predicates that require a second property are listed in Table 1 and Table 2, with the second property listed in the Second predicate property column.

Return to top

Predicates Available on Hub Transport Servers

Table 1 lists the predicates available on a Hub Transport server, and provides the following information about each predicate:

• The Predicate column lists the predicate as it appears in the New Transport Rule and Edit Transport Rule wizards in the EMC.

• The Predicate name column lists the predicate name as returned by the Get-TransportRulePredicate cmdlet.

• The Predicate property and Second predicate property columns list the property types. Most property types accept specific values. Refer to Table 3 to determine valid values for a property type.

Note

Each predicate listed in Table 1 also has an equivalent exception that can be selected from the Exceptions page of the New Transport Rule and Edit Transport Rule wizards. In the Shell, the predicates that can be used as exceptions start with ExceptIf. For example, for the FromMemberOf predicate, the parameter that can be used as an exception in transport rule cmdlets is called ExceptIfFromMemberOf.
The same predicate object contains the logic for use in a transport rule condition and exception. Therefore, when you use the Get-TransportRulePredicate cmdlet to list predicates, exceptions aren't listed as separate predicates.

Table 1   Predicates available on Hub Transport servers

No	Predicate	Predicate name	Predicate property	Second predicate property	Description
1	from people	From	Addresses	Not applicable	From matches messages sent by the specified mailboxes, mail-enabled users, or contacts. Note You can't specify a distribution group by using this predicate. If you need to create a rule that takes action on messages sent to a distribution group, use the “when any of the recipients in the To field is people” (AnyOfToHeader) predicate instead. The AnyOfToHeader predicate compares the actual values of the headers in the message. This differs from the SentTo type of predicates that compare the resolved set of recipients, including recipients found from group expansions.
2	from a member of distribution list	FromMemberOf	Addresses	Not applicable	FromMemberOf matches messages where the sender is a member of the specified distribution group.
3	from users that are inside or outside the organization	FromScope	FromUserScope	Not applicable	FromScope matches messages that are sent by senders within the specified scope.
4	sent to people	SentTo	Addresses	Not applicable	SentTo matches messages where one of the recipients is the specified mailbox, mail-enabled user, or contact. The specified recipients can be listed in the To, Cc, or Bcc fields. Note You can't specify a distribution group by using this predicate. If you need to create a rule that takes action on messages sent to a distribution group, use the “when any of the recipients in the To field is people” (AnyOfToHeader) predicate instead. The AnyOfToHeader predicate compares the actual values of the headers in the message. This differs from the SentTo type of predicates that compare the resolved set of recipients, including recipients found from group expansions.
5	sent to a member of distribution list	SentToMemberOf	Addresses	Not applicable	SentToMemberOf matches messages that contain recipients who are members of the specified distribution group. The recipients can be listed in the To, Cc, or Bcc fields.
6	sent to users that are inside or outside the organization, or partners	SentToScope	ToUserScope	Not applicable	SentToScope matches messages that are sent to recipients within the specified scope.
7	between members of distribution list and distribution list	BetweenMemberOf	Addresses (BetweenMemberOf1)	Addresses (BetweenMemberOf2)	BetweenMemberOf matches messages that are sent between members of two distribution groups.
8	when the manager of any sender is people	ManagerIs	EvaluatedUser (ManagerForEvaluatedUser)	Addresses (ManagerAddresses)	ManagerIs matches messages where the specified user's (sender or recipient) manager exists in the list of specified addresses.
9	when the sender is the manager of a recipient	ManagementRelationship	ManagementRelationship (SenderManagementRelationship)	Not applicable	ManagementRelationship matches messages where the sender has the specified management relationship with a recipient.
10	if the sender and recipient's AD Attribute are Evaluation	ADAttributeComparison	ADAttribute (ADComparisonAttribute)	Evaluation (ADComparisonOperator)	ADAttributeComparison matches messages where the sender's specified Active Directory attribute matches or doesn't match (as specified in the Evaluation property) the same attribute of any recipient.
11	when a recipient's address contains specific words	RecipientAddressContainsWords	Words	Not applicable	RecipientAddressContainsWords matches messages where a recipient's address contains any of the specified words.
12	when a recipient's address contains text patterns	RecipientAddressMatchesPatterns	Patterns	Not applicable	RecipientAddressMatchesPatterns matches messages where a recipient's address matches a specified regular expression.
13	when a recipient's properties contains specific words	RecipientAttributeContains	Words* (RecipientADAttributeContainsWords)	Not applicable	RecipientAttributeContains matches messages where the specified attribute of a recipient contains a specified string.
14	when a recipient's properties contains text patterns	RecipientAttributeMatches	Patterns* (RecipientADAttributeMatchesPatterns)	Not applicable	RecipientAttributeMatches matches messages where the specified attribute of a recipient matches a regular expression.
15	when any of the recipients in the To field is people	AnyOfToHeader	Addresses	Not applicable	AnyOfToHeader matches messages where the To field includes any of the specified recipients.
16	when any of the recipients in the "To" field is a member of distribution list	AnyOfToHeaderMemberOf	Addresses	Not applicable	AnyOfToHeaderMemberOf matches messages where the To field contains a recipient who is a member of the specified distribution group.
17	when any of the recipients in the Cc field is people	AnyOfCcHeader	Addresses	Addresses	AnyOfCcHeader matches messages where the Cc field includes any of the specified recipients.
18	when any of the recipients in the Cc field is member of distribution list	AnyOfCcHeaderMemberOf	Addresses	Not applicable	AnyOfCcHeaderMemberOf matches messages where the Cc field contains a recipient who is a member of the specified distribution group.
19	when any of the recipients in the To or Cc fields is people	AnyOfToCcHeader	Addresses	Not applicable	AnyOfToCcHeader matches messages where the To or Cc fields include any of the specified recipients.
20	when any of the recipients in the To or CC fields is a member of a distribution list	AnyOfToCcHeaderMemberOf	Addresses	Not applicable	AnyOfToCcHeaderMemberOf matches messages where the To or Cc fields contains a recipient who is a member of the specified distribution group.
21	marked with classification	HasClassification	Classification	Not applicable	HasClassification matches messages that have the specified classification.
22	when the Subject field contains specific words	SubjectContains	Words	Not applicable	SubjectContains matches messages that have the specified words in the Subject field.
23	when the Subject field or message body contains specific words	SubjectOrBodyContains	Words	Not applicable	SubjectOrBodyContains matches messages that have the specified words in the Subject field or message body.
24	when the message header contains specific words	HeaderContains	MessageHeader (HeaderContainsMessageHeader)	Words (HeaderContainsWords)	HeaderContains matches messages where the specified message header contains the specified value.
25	when the From address contains specific words	FromAddressContains	Words (FromAddressContainsWords)	Not applicable	FromAddressContains matches messages that contain the specified words in the From field.
26	when the Subject field contains text patterns	SubjectMatches	Patterns (SubjectMatchesPatterns)	Not applicable	SubjectMatches matches messages where text patterns in the Subject field match a specified regular expression.
27	when the Subject field or the message body contains text patterns	SubjectOrBodyMatches	Patterns (SubjectOrBodyMatchesPatterns)	Not applicable	SubjectOrBodyMatches matches messages where text patterns in the Subject field or message body match a specified regular expression.
28	when the message header matches text patterns	HeaderMatches	MessageHeader (HeaderMatchesMessageHeader)	Patterns (HeaderMatchesPatterns)	HeaderMatches matches messages where the specified message header contains a text pattern that matches a specified regular expression.
29	when the From address matches text patterns	FromAddressMatches	Patterns (FromAddressMatchesPatterns)	Not applicable	FromAddressMatches matches messages that contain text patterns in the From field that match a specified regular expression.
30	when any attachment file name matches text patterns	AttachmentNameMatches	Patterns (AttachmentNameMatchesPatterns)	Not applicable	AttachmentNameMatches matches messages that contain text patterns in an attachment that matches a specified regular expression.
31	with a spam confidence level (SCL) rating that is greater than or equal to limit	SCLOver	SclValue	Not applicable	SCLOver matches messages that are assigned a spam confidence level (SCL) matching or exceeding the specified value.
32	when the size of any attachment is greater than or equal to limit	AttachmentSizeOver	Size	Not applicable	AttachmentSizeOver matches messages that contain attachments larger than the specified value.
33	marked with importance	WithImportance	Importance	Not applicable	WithImportance matches messages marked with the specified priority.
34	if the message is Message Type	MessageTypeMatches	MessageType	Not applicable	MessageTypeMatches matches messages of the specified type.
35	when the sender's properties contain specific words	SenderAttributeContains	Words* (SenderADAttributeContainsWords)	Not applicable	SenderAttributeContains matches messages where the specified attribute of the sender matches a specified string.
36	when the sender's properties match text patterns	SenderAttributeMatches	Patterns (SenderADAttributeMatchesPatterns)	Not applicable	SenderAttributeMatches matches messages where the specified attribute of the sender contains text patterns that match a specified regular expression.
37	not marked with a message classification	HasNoClassifications	Not applicable	Not applicable	HasNoClassifications matches messages that don't have a message classification.
38	when an attachment's content contains words	AttachmentContainsWords	Words	Not applicable	AttachmentContainsWords matches messages with attachments that contain a specified string.
39	when an attachment's content matches text patterns	AttachmentMatchesPatterns	Patterns	Not applicable	AttachmentMatchesPatterns matches messages with attachments that contain a text pattern that matches a specified regular expression.
40	when an attachment is unsupported	AttachmentIsUnsupported	Not applicable	Not applicable	AttachmentIsUnsupported matches messages with attachments that aren't supported.

Return to top

Predicates Available on Edge Transport Servers

Table 2 lists the predicates available on Edge Transport servers.

Note

Each predicate listed in Table 1 also has an equivalent exception that can be selected from the Exceptions page of the New Transport Rule and Edit Transport Rule wizards. In the Shell, the predicates that can be used as exceptions start with ExceptIf. For example, for the FromMemberOf predicate, the parameter that can be used as an exception in transport rule cmdlets is called ExceptIfFromMemberOf.
The same predicate object contains the logic for use in a transport rule condition and exception. Therefore, when you use the Get-TransportRulePredicate cmdlet to list predicates, exceptions aren't listed as separate predicates.

Predicates available on Edge Transport servers

No	Predicate	Predicate name	Predicate property	Second predicate property	Description
1	when the subject field contains specific words	SubjectContains	Words	Not applicable	SubjectContains matches messages that contain the specified words in the Subject field.
2	when the subject field or message body contains specific words	SubjectOrBodyContains	Words	Not applicable	SubjectOrBodyContains matches messages that contain the specified words in the Subject field or message body.
3	when the message header contains specific words	HeaderContains	MessageHeader	Words	HeaderContains matches messages where the value of the specified message header contains the specified words.
4	when the From address contains specific words	FromAddressContains	Words	Not applicable	FromAddressContains matches messages that contain the specified words in the From field.
5	when any recipient address contains specific words	AnyOfRecipientAddressContainsWords	Words	Not applicable	AnyOfRecipientAddressContains matches messages that contain the specified words in the To, Cc, or Bcc fields of the message.
6	when the Subject field matches text patterns	SubjectMatches	Patterns	Not applicable	SubjectMatches matches messages where text patterns in the Subject field match a specified regular expression.
7	when the Subject field or the message body matches text patterns	SubjectOrBodyMatches	Patterns	Not applicable	SubjectOrBodyMatches matches messages where text patterns in the Subject field or message body match a specified regular expression.
8	when the message header matches text patterns	HeaderMatches	MessageHeader	Patterns	HeaderMatches matches messages where the specified message header field contains text patterns that match a specified regular expression.
9	when the From address matches text patterns	FromAddressMatches	Patterns	Not applicable	FromAddressMatches matches messages that contain text patterns in the From field of the messages that match a specified regular expression.
10	when any recipient address matches text patterns	AnyOfRecipientAddressMatches	Patterns	Not applicable	AnyOfRecipientAddressMatches matches messages where text patterns in the To, Cc, or Bcc fields of the message match a specified regular expression.
11	with a spam confidence level (SCL) rating that is greater than or equal to limit	SCLOver	SclValue	Not applicable	SclOver matches messages with an SCL that's equal to or greater than the value specified.
12	when the size of any attachment is greater than or equal to limit	AttachmentSizeOver	Size	Not applicable	AttachmentSizeOver matches messages that contain attachments larger than the specified value.
13	From users that are inside or outside the organization	FromScope	Scope	Not applicable	FromScope matches messages that are sent from the specified scope.

Return to top

Predicate Properties

The following table lists the property types used in transport rule predicates.

Table 3   Property types used in transport rule predicates

Predicate	Name	Description
ADAttribute	One of the Active Directory attributes available for use	The ADAttribute predicate accepts the name of one of the following Active Directory attributes available for use with this property type in transport rules: DisplayName FirstName Initials LastName Office PhoneNumber OtherPhoneNumber Email Street POBox City State ZipCode Country UserLogonName HomePhoneNumber OtherHomePhoneNumber PagerNumber MobileNumber FaxNumber OtherFaxNumber Notes Title Department Company Manager CustomAttribute1 - CutomAttribute15 When you use the Shell to create a transport rule consisting of the RecipientAddressContains or RecipientAddressMatches predicates, you must specify an attribute name from the preceding list followed by a colon (:) and the word or text pattern you want to match in the specified attribute. The entire notation should be enclosed in quotation marks ("). For example, to specify the attribute City and the values San Francisco or Palo Alto, you must use City:San Francisco, Palo Alto. You can also specify multiple Active Directory attributes and value pairs. For example, "City:San Francisco, Palo Alto","Department:Sales, Finance". In this case, the recipient's City attribute should contain either San Francisco or Palo Alto, and the Department attribute should contain either Sales or Finance.
Addresses and Addresses2	Array of Active Directory mailbox, contact, or distribution group objects	The Addresses and Addresses2 predicates accept a single mailbox, contact, mail-enabled user, or distribution group object.
Classification	Message classification object	The Classification predicate accepts a message classification object. To specify a message classification object, you must use the Get-MessageClassification cmdlet. For example, use the following command to search for messages with the ExCompanyInternal classification and prepend the message subject with CompanyInternal. New-TransportRule "Rule Name" -HasClassification @(Get-MessageClassification ExCompanyInternal).Identity -PrependSubject "CompanyInternal"
EvaluatedUser	Single value of Sender or Recipient	The ManagementRelationship predicate accepts an EvaluatedUser value for the ManagerForEvaluatedUser property. It instructs the Transport Rules agent whether the predicate should inspect a message's sender or the recipient.
Evaluation	Single value of Equal or NotEqual	The ADAttributeComparison predicate accepts a value of type Evaluation for the ADComparisonOperator property. This allows you to compare the specified Active Directory attribute values for the sender and recipient.
FromUserScope	Single value of InOrganization or NotInOrganization	The FromScope predicate accepts a scope value of type FromUserScope. This specifies whether the message is sent by a sender who is considered to be inside the organization. The following values can be used: InOrganization   A sender is considered to be inside the organization if either of the following conditions is true: The sender is a mailbox, mail-enabled user, distribution group, or public folder that exists in the organization's Active Directory. The domain of the sender is an accepted domain in the Exchange organization, but isn't an ExternalRelay domain. Also, the message must be sent or received by using an authenticated connection. Note To determine whether mail contacts are considered to be inside or outside the organization, the domain part of the sender's address is compared with the configured accepted domains. For more information, see Understanding Accepted Domains NotInOrganization   A sender is considered to be outside the organization if the sender's domain isn't an accepted domain in the Exchange organization and is an ExternalRelay domain.
Importance	Single value of High, Low, or Normal	The Importance predicate accepts the message priority.
ManagementRelationship	Single value of Manager or DirectReport	The ManagementRelationship predicate specifies the relationship between two evaluated users, for example the sender and the recipient. The evaluated user's Active Directory information is located to determine the manager and direct reports.
MessageHeader	Single string	The MessageHeader predicate accepts a string that can be used to specify the SMTP message header to examine. This property is used together with the Words or Patterns properties, which specify the value of the header field to match. You don't need to add a colon (:) in the header name.
MessageType	Single message type name	The MessageType predicate accepts one of the following message types: OOF AutoAccept AutoForward Encrypted Calendaring PermissionControlled Voicemail RSS Signed ApprovalRequest ReadReceipt
Patterns	Array or regular expressions	The Patterns predicate accepts a regular expression that can be used to match text that follows an identifiable pattern. Enclose the expression in quotation marks ("). For more information, see Regular Expressions in Transport Rules.
SclValue	Single integer	The SclValue predicate accepts an integer that can be used to match the spam confidence level (SCL) assigned to a message. SCL values range from -1 through 9.
Size	Single integer with quantifier such as KB or MB	The Size predicate accepts an integer that specifies the size of an e-mail attachment. When using the EMC, the value specified is in kilobytes. When using the Shell, you can enter an integer value qualified by one of the following units: B (bytes) KB (kilobytes) MB (megabytes) GB (gigabytes) For example, 20MB
ToUserScope	One of the following values: InOrganization NotInOrganization ExternalPartner ExternalNonPartner	The SentToScope predicate accepts a scope value of type ToUserScope. The InOrganization and NotInOrganization values are evaluated similar to the FromUserScope property, but in the context of the recipient. The following is a description of the other possible values: ExternalPartner   These domains are configured to send mail to an external domain by using Domain Secure security ExternalNonPartner   These represent all other domains that aren't considered ExternalPartner domains.
Words	Array of strings	The Words property accepts one string or an array of strings. It's used in all predicates that inspect different parts of a message for specific words or strings. In Exchange 2010, only instances of the word without a prefix or suffix are matched. For example, if you specify the word "contoso", the rule will fire only if an exact match is found. The following variations where the word appears as a suffix, a prefix, or between other characters (other than the space character) aren't considered an exact match: Acontoso Contosoa Acontosob The property isn't case-sensitive. The asterisk (*) is treated as a literal character, and not used as a wildcard character.

Return to top

 © 2010 Microsoft Corporation. All rights reserved.