Transport Rule Predicates

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

Topic Last Modified: 2013-01-22

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.

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.

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

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.

from a member of distribution list

FromMemberOf

Addresses

Not applicable

FromMemberOf matches messages where the sender is a member of the specified distribution group.

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.

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:

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

when any of the recipients in the Cc field is people

AnyOfCcHeader

Addresses

AnyOfCcHeader matches messages where the Cc field includes any of the specified recipients.

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.

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.

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.

marked with classification

HasClassification

Classification

Not applicable

HasClassification matches messages that have the specified classification.

when the Subject field contains specific words

SubjectContains

Words

Not applicable

SubjectContains matches messages that have the specified words in the Subject field.

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.

when the message header contains specific words

HeaderContains

MessageHeader (HeaderContainsMessageHeader)

Words (HeaderContainsWords)

HeaderContains matches messages where the specified message header contains the specified value.

when the From address contains specific words

FromAddressContains

Words (FromAddressContainsWords)

Not applicable

FromAddressContains matches messages that contain the specified words in the From field.

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.

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.

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.

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.

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.

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.

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.

marked with importance

WithImportance

Importance

Not applicable

WithImportance matches messages marked with the specified priority.

if the message is Message Type

MessageTypeMatches

MessageType

Not applicable

MessageTypeMatches matches messages of the specified type.

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.

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.

not marked with a message classification

HasNoClassifications

Not applicable

HasNoClassifications matches messages that don't have a message classification.

when an attachment's content contains words

AttachmentContainsWords

Words

Not applicable

AttachmentContainsWords matches messages with attachments that contain a specified string.

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.

when an attachment is unsupported

AttachmentIsUnsupported

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.

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