Transport Rule Actions

Transport Rule Actions

Exchange 2007

Transport Rule Actions

Applies to: Exchange Server 2007, Exchange Server 2007 SP1 Topic Last Modified: 2006-11-15

This topic describes the transport rule actions that are available for a computer that has the Microsoft Exchange Server 2007 Hub Transport server role or the Edge Transport server role installed. This topic also describes the action properties and values. Both the Hub Transport server role and the Edge Transport server role can apply transport rules to e-mail messages that pass through the server roles. However, the actions that are available for each server role are different.

Actions and Action Properties

Actions are applied to e-mail messages that match the conditions and none of the exceptions that are present on transport rules, which are configured on Transport Rules agents. Each action affects e-mail messages in a different way. For example, an action can cause an e-mail message to be redirected to another address or to be dropped. 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. See Table 2 for the action properties that you must use for Hub Transport servers. See Table 3 for the action properties that you must use for Edge Transport servers.

Some actions require that you set two or more predicate 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 from the Additional Action Property column in Table 2 or Table 3, 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.

Table 1 lists the action properties that you can use with transport rules that are configured on a Hub Transport server or an Edge Transport server.

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

Action property Expected format Description

Addresses

Edge Transport server Array of Simple Mail Transfer Protocol (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 double quotation marks. For a detailed description of how to use this action property on an Edge Transport server, see "Assigning Addresses on an Edge Transport Server" later in this topic.

On a Hub Transport server, Addresses accepts an array of mailbox, contact, mail-enabled user, or distribution group objects. For a detailed description of how to use this action property on a Hub Transport server, see "Assigning Addresses on a Hub Transport Server" later in this topic.

Classification

Single message classification object

Classification accepts a single message classification object. To specify a message classification object, use the Get-MessageClassification command. For example, use the following command to apply the ExCompanyInternal message classification to an action:

$Action.Classification = (Get-MessageClassification ExCompanyInternal).Identity

For more information about message classification, see Overview of Message Classifications.

EnhancedStatusCode

Single delivery status notification (DSN) code of 5.7.1, or any value between 5.7.10 to 5.7.999.

EnhancedStatusCode specifies the DSN code and related DSN message to display to the senders of messages that are rejected by the RejectMessage transport rule action. The DSN message that is associated with the specified DSN status code is displayed in the user information portion of the NDR that is 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 that is 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 as, for example, when a message is encrypted. The default fallback action is Wrap. Enclose the value in double quotation marks. The following list shows each fallback action and its description:

Wrap If the disclaimer cannot 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, 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 is not delivered. The sender of the message receives a non-delivery report (NDR) that explains why the message was not 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.

Font

Single value with the choices of Arial, CourierNew, or Verdana

Font specifies the font of the disclaimer text when the text is added to an e-mail message. The default font is Arial. Enclose the value in double quotation marks.

FontColor

Single value with the choices of Black, Blue, Fuchsia, Gray, Green, Lime, Maroon, Navy, Olive, Purple, Red, Silver, Teal, White, or Yellow

FontColor specifies the color of the font of the disclaimer text when the text is added to an e-mail message. The default color is Gray. Enclose the value in double quotation marks.

FontSize

Single value with the choices of Smallest, Smaller, Normal, Larger, or Largest

FontSize specifies the size of the font of the disclaimer text when the text is added to an e-mail message. The default size is Smallest. Enclose the value in double quotation marks.

HeaderValue

Single string

HeaderValue accepts a single string that is applied to the header that is specified by using the MessageHeader action property. Enclose the string in double quotation marks.

Location

Single value with the choices of Append or Prepend

Location specifies where the disclaimer is inserted into the e-mail message. Append puts the disclaimer at the bottom of the e-mail message thread. Prepend puts the disclaimer at the start of the newest e-mail message. Enclose the value in double quotation marks.

MessageHeader

Single string

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

Prefix

Single string

Prefix accepts a string that is prepended to the subject of the e-mail message. Enclose the string in double quotation marks.

To prevent the string that is 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 does not 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 is used to populate the administrator information portion of the NDR that is returned to the e-mail sender if an e-mail message is rejected. Enclose the string in double quotation marks.

SclValue

Single Integer

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

Separator

Single value with the choices WithSeparator or WithoutSeparator

Separator specifies whether a separator is placed between the disclaimer and the e-mail message body. Enclose the value in double quotation marks.

Text

Single string

Text accepts a string that is used to populate the disclaimer message that is added to an e-mail message. Enclose the string in double quotation marks.

Supported Actions on a Hub Transport Server

Table 2 lists the actions that can be used with transport rules that are configured on a Hub Transport server.

Table 2 Supported actions for transport rules on a Hub Transport server

Supported rule action	Action name	First action property	Additional action property	Description
log an event with message	`LogEvent`	`EventMessage`	Not applicable	`LogEvent` adds 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.
apply message classification	`ApplyClassification`	`Classification`	Not applicable	`ApplyClassification` applies a message classification to the e-mail message. For more information about message classifications, see Overview of Message Classifications.
append disclaimer text using font, size, color, with separator, and fallback to action if unable to apply	`ApplyDisclaimer`	`Text`	`Location`, `Font`, `FontSize`, `FontColor`, `FallbackAction, Separator`	`ApplyDisclaimer` applies a disclaimer to the e-mail message. For more information about disclaimers, see Overview of Disclaimers.
set the spam confidence level to value	`SetScl`	`SclValue`	Not applicable	`SetScl` sets the spam confidence level (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 recipients to the To address list of the e-mail message. The original recipients can see the additional address.
copy message to addresses	`CopyTo`	`Addresses`	Not applicable	`CopyTo` adds one or more e-mail recipients to the carbon copy (Cc) field of the e-mail message. The original recipients can see the original address.
blind copy (Bcc) the message to addresses	`BlindCopyTo`	`Addresses`	Not applicable	`BlindCopyTo` adds one or more e-mail recipients to the blind carbon copy (Bcc) address list of the e-mail message. The original recipients aren't notified and can't see the additional address.
redirect message to addresses	`RedirectMessage`	`Addresses`	Not applicable	`RedirectMessage` redirects the e-mail message to one or more e-mail recipients that are specified by the administrator. The message isn't delivered to the original recipient or recipients, and no notification is sent to the recipients or the sender.
send bounce 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.
silently drop the message	`DeleteMessage`	Not applicable	Not applicable	`DeleteMessage` deletes the e-mail message without sending a notification to either the recipient or the sender.

Supported Actions on an Edge Transport Server

Table 3 lists the actions that can be used with transport rules that are configured on an Edge Transport server.

Table 3 Supported actions for transport rules on an Edge Transport server

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 spam confidence level (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 carbon copy (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 blind carbon copy (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

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 that are 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 quarantine

Quarantine

Not applicable

Quarantine redirects the e-mail message to the spam quarantine mailbox that is 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 quarantine 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 a non-delivery report will be generated.

For more information about the spam quarantine mailbox, see Configuring and Managing 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.

silently drop the message

DeleteMessage

Not applicable

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

Assigning Addresses on a Hub Transport Server

The Addresses action property on a Hub Transport server requires that you pass a full mailbox, contact, mail-enabled user, or distribution group object to the property. Simple Mail Transfer Protocol (SMTP) e-mail addresses aren't valid values for this property. Values that are assigned to the Addresses action property must be in an array.

To pass a mailbox, contact, mail-enabled user, or distribution group object to the Addresses action property, you must call the appropriate Exchange Management Shell command from within the array and supply the command with the identity or name of the object. You must enclose the command name and identity in parentheses. Use the following command syntax:

$Action.Addresses = @((Get-Mailbox <Mailbox Name>), (Get-MailContact <Contact Name>), (Get-MailUser <Mail-Enabled User>), (Get-DistributionGroup <Distribution Group Name>))

To assign values to the Addresses action property

Run the following command to assign a single mailbox object:
```
$Action.Addresses = @((Get-Mailbox "Ted Bremer"))
```
Run the following command to assign a single mail contact object:
```
$Action.Addresses = @((Get-MailContact "Masato Kawai"))
```
Run the following command to assign a single mail-enabled user object:
```
$Action.Addresses = @((Get-MailUser "Pilar Ackerman"))
```
Run the following command to a single distribution group object:
```
$Action.Addresses = @((Get-DistributionGroup "Sales Group"))
```

Run the following command to assign a mix of mailbox, user, and distribution group objects:

$Action.Addresses = @((Get-Mailbox "Ted Bremer"), (Get-Mailbox "Kim Akers"), (Get-MailContact "Pilar Ackerman"), (Get-MailContact "Adam Barr"), (Get-MailUser "Chris Meyer"), (Get-DistributionGroup "Marketing Group"), (Get-DistributionGroup "Research Group"))

Assigning Addresses on an Edge Transport Server

The Addresses action property on an Edge Transport server requires that you pass an SMTP e-mail address to the property. This is because Edge Transport servers do not have access to the recipient objects contained in the Active Directory directory service and because you may want to specify an e-mail address that is not within your Exchange organization. Values that are assigned to the Addresses action property must be in an array.

To pass an SMTP address to the Addresses action property, you must call enclose the SMTP e-mail address in double quotation marks. Use the following command syntax:

$Action.Addresses = @("<SMTP e-mail address 1>","<SMTP e-mail address 2>", "< SMTP e-mail address...>" )

To assign values to the Addresses action property

Run the following command to assign an array of SMTP e-mail addresses:

$Action.Addresses = @("sales@contoso.com", "research@contoso.com", "investors@nwtraders.com ")

For More Information

For detailed syntax and parameter information about each command, see the following topics:

For more information about transport rules, see the following topics:

Manage Your Profile | Contact Us | Newsletter

Product Families

Resources

About Microsoft

Popular Places

Popular Searches

Popular Downloads

Exchange Server TechCenter

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

Table 2 Supported actions for transport rules on a Hub Transport server

Table 3 Supported actions for transport rules on an Edge Transport server