Transport Rule Actions

 

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

Transport rule actions instruct the rules agent to take the specified action on messages that match all the predicates in a condition, and don't match any of the exceptions. In Microsoft Exchange Server 2010, both the Hub Transport server and Edge Transport server can apply transport rules to e-mail messages routed by them. Some actions are available on both transport server roles, and some are exclusive to either role.

Each action affects e-mail messages in a unique way. For example, an action can cause an e-mail message to be redirected to another address or to be deleted. Each action consists of the action itself, its action property, and the value of the property.

To assign a value to an action, you must determine the available action property for a specific action. For example, you must use the Address action property together with the RedirectMessage action. (For information about the action properties available for use with Hub Transport servers and Edge Transport servers, see the tables later in this topic.)

Some actions require that you set two or more action properties, because some actions modify specific fields within sections of an e-mail message, such as the message header fields. When you specify an action to modify a message header, one action property specifies the specific header field to modify, and a second action property specifies the new value of the message header. In these cases, you must also specify a value for the second action property, as shown later in this topic in the Additional action property table column in either Actions Available on a Hub Transport Server or Actions Available on an Edge Transport Server, depending on the server role. For example, you can configure an action to modify the X-Test-Message-Source header field to a specific string, such as contoso.com.

You can use either the Exchange Management Console or the Exchange Management Shell to create or modify a transport rule. For relevant procedures, see Transport Rules.

Contents

Actions Available on a Hub Transport Server

Actions Available on an Edge Transport Server

Action Properties for Transport Rules on a Hub Transport or an Edge Transport Server

For More Information

Actions Available on a Hub Transport Server

The following table lists the actions that can be used with transport rules on a server running Exchange 2010 that has the Hub Transport server role installed. The transport rule action LogEvent isn't available on Exchange 2010 Hub Transport servers.

Transport rule actions available on Hub Transport servers

Supported rule action Action name First action property Additional action property Description

prepend the subject with string

PrependSubject

Prefix

Not applicable

PrependSubject prepends a string to the start of the Subject field of the message.

apply message classification

ApplyClassification

Classification

Not applicable

ApplyClassification applies a message classification to the e-mail message.

For more information, see Understanding Message Classifications.

append disclaimer text and fallback to action if unable to apply

ApplyHtmlDisclaimer

ApplyHtmlDisclaimerLocation

ApplyHtmlDisclaimerText, ApplyHtmlDisclaimerFallbackAction

ApplyHtmlDisclaimer applies an HTML disclaimer to the message. For more information, see Understanding Disclaimers.

rights protect message with RMS template

RightsProtectMessage

RMSTemplateIdentity

Not applicable

RightsProtectMessage applies the specified Rights Management Services (RMS) template to the message. For more information, see Understanding Transport Protection Rules.

set the spam confidence level to value

SetScl

SclValue

Not applicable

SetScl sets the spam confidence level (SCL) on an e-mail message. For more information, see Understanding Spam Confidence Level Threshold.

set header with value

SetHeader

MessageHeader

HeaderValue

SetHeader creates a new message header field or modifies an existing message header field.

remove header

RemoveHeader

MessageHeader

Not applicable

RemoveHeader removes the specified message header field from a message.

add a recipient in the To field addresses

AddToRecipient

Addresses

Not applicable

AddToRecipient adds one or more recipients to the To field of the message. The original recipients can see the additional address.

copy the message to addresses

CopyTo

Addresses

Not applicable

CopyTo adds one or more recipients to the carbon copy (Cc) field of the message. The original recipients can see the Cc address.

Blind carbon copy (Bcc) the message to addresses

BlindCopyTo

Addresses

Not applicable

BlindCopyTo adds one or more recipients as blind carbon copy (Bcc) recipients. The original recipients aren't notified and can't see the Bcc addresses.

add the sender's manager as a specific recipient type

AddManagerAsRecipientType

AddedRecipientType

Not applicable

AddManagerAsRecipientType adds the sender's manager, if defined in the manager attribute in Active Directory, as the specified recipient type.

forward the message to addresses for moderation

ModerateMessageByUser

Addresses

Not applicable

ModerateMessageByUser forwards the message to the specified moderators as an attachment wrapped in an approval request. For more information, see Understanding Moderated Transport.

forward the message to the sender's manager for moderation

ModerateMessageByManager

Not applicable

Not applicable

ModeratedMessageByManager forwards the message to the sender's manager for moderation, if the manager attribute is populated in Active Directory.

Important

If the sender's manager attribute isn't populated in Active Directory, the message is delivered to recipients without moderation.

This action doesn't require any action properties.

redirect the message to addresses

RedirectMessage

Addresses

Not applicable

RedirectMessage redirects the e-mail message to one or more recipients specified by the administrator. The message isn't delivered to the original recipients, and no notification is sent to the sender or the original recipients.

send rejection message to sender with enhanced status code

RejectMessage

RejectReason

EnhancedStatusCode

RejectMessage deletes the e-mail message and sends a non-delivery receipt to the sender. The recipient doesn't receive the message or notification.

Delete the message without notifying anyone

DeleteMessage

Not applicable

Not applicable

DeleteMessage deletes the e-mail message without sending a notification to either the recipient or the sender.

Return to top

Actions Available on an Edge Transport Server

The following table lists the actions that can be used with transport rules on Exchange 2010 Edge Transport servers.

Transport rule actions available on Edge Transport servers

Supported rule action Action name First action property Additional action property Description

log an event with message

LogEvent

EventMessage

Not applicable

LogEvent inserts an event into the Application log of the local computer.

prepend the subject with string

PrependSubject

Prefix

Not applicable

PrependSubject prepends a string to the start of the e-mail message subject field.

set the spam confidence level to value

SetScl

SclValue

Not applicable

SetScl configures the SCL on an e-mail message.

set header with value

SetHeader

MessageHeader

HeaderValue

SetHeader creates a new message header field or modifies an existing message header field.

remove header

RemoveHeader

MessageHeader

Not applicable

RemoveHeader removes the specified message header field from an e-mail message.

add a recipient in the To field addresses

AddToRecipient

Addresses

Not applicable

AddToRecipient adds one or more e-mail addresses to the To address list of the e-mail message. The original recipients can see the additional address.

copy the message to addresses

CopyTo

Addresses

Not applicable

CopyTo adds one or more e-mail addresses to the Cc field of the e-mail message. The original recipients can see the original address.

Blind carbon copy (Bcc) the message to addresses

BlindCopyTo

Addresses

Not applicable

BlindCopyTo adds one or more e-mail addresses to the Bcc address list of the e-mail message. The original recipients aren't notified and can't see the additional address.

drop connection

Disconnect

Not applicable

Not applicable

Disconnect ends the connection between the sending server and the Edge Transport server without generating an NDR message.

redirect the message to addresses

RedirectMessage

Addresses

Not applicable

RedirectMessage redirects the e-mail message to one or more e-mail addresses specified by the administrator. The message isn't delivered to the original recipient, and no notification is provided to the recipient or the sender.

Put message in spam quarantine mailbox

Quarantine

Not applicable

Not applicable

Quarantine redirects the e-mail message to the spam quarantine mailbox configured by using the QuarantineMailbox parameter on the Set-ContentFilterConfig cmdlet.

Important

The QuarantineMailbox parameter on the Set-ContentFilterConfig cmdlet must be populated, and the specified mailbox must exist before you configure the Put message in spam quarantine mailbox action. If the QuarantineMailbox parameter isn't populated or if the quarantine mailbox doesn't exist, messages sent to the quarantine mailbox will be lost and an NDR will be generated.

For more information about the spam quarantine mailbox, see Understanding Spam Quarantine.

reject the message with status code and response

SmtpRejectMessage

StatusCode

RejectReason

SmtpRejectMessage deletes the e-mail message and sends a notification to the sender. The recipients don't receive the message or notification. This action enables you to specify a specific delivery status notification (DSN) code.

For more information about DSNs, see Managing Delivery Status Notifications.

Delete the message without notifying anyone

DeleteMessage

Not applicable

Not applicable

DeleteMessage deletes the e-mail message without sending a notification to either the recipient or the sender.

Return to top

Action Properties for Transport Rules on a Hub Transport or an Edge Transport Server

The following table lists the action properties used by transport rules actions on Exchange 2010 Hub Transport or Edge Transport servers.

Action properties for transport rules on a Hub Transport server or an Edge Transport server

Action property Expected format Description

AddedRecipientType

One of the following values:

  • To

  • Cc

  • Bcc

  • Redirect

AddedRecipientType accepts a single value:

  • To, Cc, and Bcc values are self-explanatory and correspond to the addressing fields of e-mail messages.

  • Redirect delivers the message only to the specified recipient. The message isn't delivered to any of the original recipients.

Addresses

  • Edge Transport server   Array of SMTP addresses

  • Hub Transport server   Array of Active Directory mailbox, contact, mail-enabled user, or distribution group objects

On an Edge Transport server, Addresses accepts an array of SMTP addresses that are each enclosed in quotation marks (").

On a Hub Transport server, Addresses accepts an array of mailbox, contact, mail-enabled user, or distribution group objects.

Classification

Single message classification object

Classification accepts a single message classification object. To specify a message classification object, use the Get-MessageClassification cmdlet.

For more information about message classifications, see Understanding Message Classifications.

DisclaimerLocation

One of the following values:

  • Append

  • Prepend

DisclaimerLocation specifies where the disclaimer is inserted into the e-mail message:

  • Append (default) adds the disclaimer at the bottom of the message thread.

  • Prepend puts the disclaimer at the start of the newest e-mail message.

EnhancedStatusCode

Single DSN code of 5.7.1, or any value from 5.7.10 through 5.7.999

EnhancedStatusCode specifies the DSN code and related DSN message to display to the senders of messages rejected by the RejectMessage transport rule action. The DSN message associated with the specified DSN status code is displayed in the user information portion of the NDR displayed to the sender. The specified DSN code must be an existing default DSN code or a customized DSN status code that you can create by using the New-SystemMessage cmdlet.

EventMessage

Single string

EventMessage accepts a single string displayed in an event log, which is added to the application event log on the local computer.

FallbackAction

Single value with the choices of Wrap, Ignore, or Reject

FallbackAction specifies what the transport rule should do if a disclaimer can't be applied to an e-mail message such as when a message is encrypted. The default fallback action is Wrap. Enclose the value in quotation marks ("). The following list shows each fallback action and its description:

  • Wrap   If the disclaimer can't be inserted into the original message, Exchange encloses, or wraps, the original message in a new message envelope. Then the disclaimer is inserted into the new message.

    Important

    If an original message is wrapped in a new message envelope, subsequent transport rules are applied to the new message envelope, and not to the original message. Therefore, you must configure transport rules with disclaimer actions that wrap original messages in a new message body after you configure other transport rules.

    Note

    If the original message can't be wrapped in a new message envelope, the original message isn't delivered. The sender of the message receives an NDR that explains why the message wasn't delivered.

  • Ignore   If the disclaimer can't be inserted into the original message, Exchange lets the original message continue unmodified. No disclaimer is added.

  • Reject   If the disclaimer can't be inserted into the original message, Exchange doesn't deliver the message. The sender of the message receives an NDR that explains why the message wasn't delivered.

HeaderValue

Single string

HeaderValue accepts a single string that's applied to the header specified by using the MessageHeader action property. Enclose the string in quotation marks (").

MessageHeader

Single string

MessageHeader accepts a string that specifies which MessageHeader to add or modify. The string that's specified by using the HeaderValue action property is inserted into the header that's specified by MessageHeader. Enclose the string in quotation marks (").

Prefix

Single string

Prefix accepts a string that's prepended to the subject of the e-mail message. Enclose the string in quotation marks (").

To prevent the string that's specified with the Prefix transport rule action from being added to the subject every time that a reply to the message encounters the transport rule, add the SubjectContains exception to the transport rule.

The SubjectContains exception should contain the string that you specified with the Prefix transport rule action. If you add the SubjectContains exception to the transport rule, the transport rule doesn't add another instance of the Prefix string to the subject if the Prefix string already appears in the subject.

RejectReason

Single string

RejectReason accepts a string that's used to populate the administrator information portion of the NDR returned to the e-mail sender if an e-mail message is rejected. Enclose the string in quotation marks (").

RMSTemplateIdentity

RMS Template identity

RMSTemplateIdentity accepts an RMS Template identity. You can get a list of RMS templates available on an Active Directory RMS server in the Active Directory forest using the Get-RMSTemplate cmdlet.

SclValue

Single integer

SclValue accepts a single integer from 0 through 9, which is used to configure the SCL of the e-mail message. Enclose the integer in quotation marks (").

Return to top

For More Information

Understanding Transport Rules

Transport Rule Predicates

Configure a Disclaimer

Regular Expressions in Transport Rules

 © 2010 Microsoft Corporation. All rights reserved.