Mail flow rule actions in Exchange Online

In Exchange Online organizations or standalone Exchange Online Protection (EOP) organizations without Exchange Online mailboxes, actions in mail flow rules (also known as transport rules) specify what you want to do to messages that match conditions of the rule. For example, you can create a rule that forwards messages from specific senders to a moderator, or adds a disclaimer or personalized signature to all outbound messages.

Actions typically require additional properties. For example, when the rule redirects a message, you need to specify where to redirect the message. Some actions have multiple properties that are available or required. For example, when the rule adds a header field to the message header, you need to specify both the name and value of the header. When the rule adds a disclaimer to messages, you need to specify the disclaimer text, but you can also specify where to insert the text, or what to do if the disclaimer can't be added to the message. Typically, you can configure multiple actions in a rule, but some actions are exclusive. For example, one rule can't reject and redirect the same message.

For more information about mail flow rules, including how multiple actions are handled, see Mail flow rules (transport rules) in Exchange Online.

For more information about conditions and exceptions in mail flow rules, see Mail flow rule conditions and exceptions (predicates) in Exchange Online.

For more information about actions in mail flow rules in Exchange Server, see Mail flow rule actions in Exchange Server.

Actions for mail flow rules in Exchange Online

The actions that are available in mail flow rules in Exchange Online and standalone EOP are described in the following table. Valid values for each property are described in the Property values section.

Notes:

  • After you select an action in the Exchange admin center (EAC), the value that's ultimately shown in the Do the following field is often different from the click-path you selected. Also, when you create new rules, you can sometimes (depending on the selections you make) select a short action name from a template (a filtered list of actions) instead of following the complete click-path. The short names and full click-path values are shown in the EAC column in the table.

  • The names of some of the actions that are returned by the Get-TransportRuleAction cmdlet are different than the corresponding parameter names, and multiple parameters might be required for an action.

Action in the EAC Action parameter in PowerShell Property Description
Forward the message for approval to

Forward the message for approval > to these people

ModerateMessageByUser Addresses Forwards the message to the specified moderators as an attachment wrapped in an approval request. For more information, see Use mail flow rules for message approval scenarios in Exchange Online. You can't use a distribution group as a moderator.

Note: This action isn't available in standalone Exchange Online Protection (EOP) environments.

Forward the message for approval to the sender's manager

Forward the message for approval > to the sender's manager

ModerateMessageByManager n/a Forwards the message to the sender's manager for approval.

This action only works if the sender's Manager attribute is defined. Otherwise, the message is delivered to the recipients without moderation.

Note: This action isn't available in standalone EOP environments.

Redirect the message to

Redirect the message to > these recipients

RedirectMessageTo Addresses Redirects the message to the specified recipients. The message isn't delivered to the original recipients, and no notification is sent to the sender or the original recipients.
Deliver the message to the hosted quarantine

Redirect the message to > hosted quarantine

Quarantine n/a Delivers the message to the quarantine. For more information, see Quarantined email messages in EOP.
If the action is executed for a rule that's not last in the rule collection, as soon as the action is executed, current rule evaluation is stopped. When the message is released from Quarantine, rest of the rules in the rule collection (that are not evaluated initially because message is sent to quarantine) aren't evaluated at all.
Use the following connector

Redirect the message to > the following connector

RouteMessageOutboundConnector OutboundConnector Uses the specified outbound connector to deliver the message. For more information about connectors, see Configure mail flow using connectors.
Reject the message with the explanation

Block the message > reject the message and include an explanation

RejectMessageReasonText String Returns the message to the sender in a non-delivery report (also known as an NDR or bounce message) with the specified text as the rejection reason. The recipient doesn't receive the original message or notification.

The default enhanced status code that's used is 5.7.1.

When you create or modify the rule in PowerShell, you can specify the DSN code by using the RejectMessageEnhancedStatusCode parameter.

Reject the message with the enhanced status code

Block the message > reject the message with the enhanced status code of

RejectMessageEnhancedStatusCode DSNEnhancedStatusCode Returns the message to the sender in an NDR with the specified enhanced delivery status notification (DSN) code. The recipient doesn't receive the original message or notification.

Valid DSN codes are 5.7.1 or 5.7.900 through 5.7.999.

The default reason text that's used is Delivery not authorized, message refused.

When you create or modify the rule in PowerShell, you can specify the rejection reason text by using the RejectMessageReasonText parameter.

Delete the message without notifying anyone

Block the message > delete the message without notifying anyone

DeleteMessage n/a Silently drops the message without sending a notification to the recipient or the sender.
Add recipients to the Bcc box

Add recipients > to the Bcc box

BlindCopyTo Addresses Adds one or more recipients to the Bcc field of the message. The original recipients aren't notified, and they can't see the additional addresses.

Note: In Exchange Online, you can't add a distribution group as a recipient.

Add recipients to the To box

Add recipients > to the To box

AddToRecipients Addresses Adds one or more recipients to the To field of the message. The original recipients can see the additional addresses.

Note: In Exchange Online, you can't add a distribution group as a recipient.

Add recipients to the Cc box

Add recipients > to the Cc box

CopyTo Addresses Adds one or more recipients to the Cc field of the message. The original recipients can see the additional address.

Note: In Exchange Online, you can't add a distribution group as a recipient.

Add the sender's manager as a recipient

Add recipients > add the sender's manager as a recipient

AddManagerAsRecipientType AddedManagerAction Adds the sender's manager to the message as the specified recipient type (To, Cc, Bcc), or redirects the message to the sender's manager without notifying the sender or the recipient.

This action only works if the sender's Manager attribute is defined in Active Directory.

Append the disclaimer

Apply a disclaimer to the message > append a disclaimer

ApplyHtmlDisclaimerText
ApplyHtmlDisclaimerFallbackAction
ApplyHtmlDisclaimerLocation
First property: DisclaimerText
Second property: DisclaimerFallbackAction
Third property (PowerShell only): DisclaimerTextLocation
Applies the specified HTML disclaimer to the end of the message.
When you create or modify the rule in PowerShell, use the ApplyHtmlDisclaimerLocation parameter with the value Append.
Prepend the disclaimer

Apply a disclaimer to the message > prepend a disclaimer

ApplyHtmlDisclaimerText
ApplyHtmlDisclaimerFallbackAction
ApplyHtmlDisclaimerLocation
First property: DisclaimerText
Second property: DisclaimerFallbackAction
Third property (PowerShell only): DisclaimerTextLocation
Applies the specified HTML disclaimer to the beginning of the message.
When you create or modify the rule in PowerShell, use the ApplyHtmlDisclaimerLocation parameter with the value Prepend.
Remove this header

Modify the message properties > remove a message header

RemoveHeader MessageHeaderField Removes the specified header field from the message header.
Set the message header to this value

Modify the message properties > set a message header

SetHeaderName
SetHeaderValue
First property: MessageHeaderField
Second property: String
Adds or modifies the specified header field in the message header, and sets the header field to the specified value.
Apply a message classification

Modify the message properties > apply a message classification

ApplyClassification MessageClassification Applies the specified message classification to the message.

Note: This action isn't available in standalone EOP environments.

Set the spam confidence level (SCL) to

Modify the message properties > set the spam confidence level (SCL)

SetSCL SCLValue Sets the spam confidence level (SCL) of the message to the specified value.
Apply Office 365 Message Encryption and rights protection

Apply Message Encryption and rights protection to the message with

Modify the message security > Message Encryption and rights protection

ApplyRightsProtectionTemplate RMSTemplate Applies the specified Azure Rights Management (Azure RMS) template to the message. Azure RMS is part of Azure Information Protection. For more information, see Set up new Message Encryption capabilities.
Require TLS encryption

Modify the message security > require TLS encryption

RouteMessageOutboundRequireTls n/a Forces the outbound messages to be routed over a TLS encrypted connection.
Encrypt the messages with the previous version of OME

Modify the message security > Apply Office the previous version of OME

ApplyOME n/a If you haven't moved your Microsoft 365 or Office 365 organization to Microsoft Purview Message Encryption that's built on Azure Information Protection, this action encrypts the message and attachments with the previous version of OME.

Notes:

  • We recommend that you make a plan to move to OME on Azure Information Protection as soon as it's reasonable for your organization. For instructions, see Set up new Message Encryption capabilities.
  • If you receive an error stating that IRM licensing isn't enabled, you can't set up the previous version of OME. If you set up OME now, you'll set up the OME capabilities that are built on Azure Information Protection.
    Remove the previous version of OME from the message

    Modify the message security > Remove the previous version of OME

    RemoveOME n/a Decrypt the message and attachments from the previous version of OME so that users don't need to sign in to the encryption portal to view them. This action is only available for messages that are sent within your organization.
    Remove Office 365 Message Encryption and rights protection

    Modify the message security > Message Encryption and rights protection

    RemoveOMEv2 n/a Remove the Azure RMS template from the message.
    Prepend the subject of the message with PrependSubject String Adds the specified text to the beginning of the Subject field of the message. Consider using a space or a colon (:) as the last character of the specified text to differentiate it from the original subject text.
    To prevent the same string from being added to messages that already contain the text in the subject (for example, replies), add the The subject includes (ExceptIfSubjectContainsWords) exception to the rule.
    Generate incident report and send it to GenerateIncidentReport
    IncidentReportContent
    First property: Addresses
    Second property: IncidentReportContent
    Sends an incident report that contains the specified content to the specified recipients.

    If the rule with this action is matched, this action is going to be executed even if the rule is in Audit or AuditAndNotify mode.
    Note that GenerateIncidentReport action will not be executed for the notifications or other incident reports generated by DLP or Mail flow rules.

    Notify the recipient with a message GenerateNotification NotificationMessageText Specifies the text, HTML tags, and message keywords to include in the notification message that's sent to the message's recipients. For example, you can notify recipients that the message was rejected by the rule, or marked as spam and delivered to their Junk Email folder.
    If the rule with this action is matched, this action is going to be executed even if the rule is in AuditAndNotify mode, but it will not be executed if the rule is in the Audit mode.
    Properties of this rule section > Audit this rule with severity level SetAuditSeverity AuditSeverityLevel Specifies whether to:
    • Prevent the generation of an incident report and the corresponding entry in the message tracking log.
    • Generate an incident report and the corresponding entry in the message tracking log with the specified severity level (low, medium, or high).
    Properties of this rule section > Stop processing more rules

    More options > Properties of this rule section > Stop processing more rules

    StopRuleProcessing n/a Specifies that after the message is affected by the rule, the message is exempt from processing by other rules.

    Property values

    The property values that are used for actions in mail flow rules are described in the following table:

    Property Valid values Description
    AddedManagerAction One of the following values:
    • To
    • Cc
    • Bcc
    • Redirect
    Specifies how to include the sender's manager in messages.

    If you select To, Cc, or Bcc, the sender's manager is added as a recipient in the specified field.

    If you select Redirect, the message is only delivered to the sender's manager without notifying the sender or the recipient.

    This action only works if the sender's Manager is defined.

    Addresses Exchange recipients Depending on the action, you might be able to specify any mail-enabled object in the organization, or you might be limited to a specific object type. Typically, you can select multiple recipients, but you can only send an incident report to one recipient.
    AuditSeverityLevel One of the following values:
    • Uncheck Audit this rule with severity level, or select Audit this rule with severity level with the value Not specified (DoNotAudit)
    • Low
    • Medium
    • High
    The values Low, Medium, or High specify the severity level that's assigned to the incident report and to the corresponding entry in the message tracking log.

    The other value prevents an incident report from being generated, and prevents the corresponding entry from being written to the message tracking log.

    DisclaimerFallbackAction One of the following values:
    • Wrap
    • Ignore
    • Reject
    Specifies what to do if the disclaimer can't be applied to a message (for example, encrypted or signed messages where the contents can't be altered). The available fallback actions are:
    • Wrap: A new message is created and the original message is added to it as an attachment. The disclaimer text is added to the new message, which is delivered to the recipients. This value is the default value.
      • If you want other rules to examine and act on the original message (which is now an attachment in the new message), ensure that those rules are applied before the disclaimer rule by using a lower priority for the disclaimer rule and higher priority for other rules.
      • If the process of inserting the original message as an attachment in the new message fails, the original message isn't delivered. The original message is returned to the sender in an NDR.
    • Ignore: The rule is ignored and the original message is delivered without the disclaimer.
    • Reject: The original message is returned to the sender in an NDR.
    DisclaimerText HTML string Specifies the disclaimer text, which can include HTML tags, inline cascading style sheet (CSS) tags, and images by using the IMG tag. The maximum length is 5000 characters, including tags.
    DisclaimerTextLocation Single value: Append or Prepend In PowerShell, you use the ApplyHtmlDisclaimerLocation parameter to specify the location of the disclaimer text in the message:
    • Append: Add the disclaimer to the end of the message body. This value is the default value.
    • Prepend: Add the disclaimer to the beginning of the message body.
    DSNEnhancedStatusCode Single DSN code value:
    • 5.7.1
    • 5.7.900 through 5.7.999
    Specifies the DSN code that's used. You can create custom DSNs by using the New-SystemMessage cmdlet.

    If you don't specify the rejection reason text along with the DSN code, the default reason text that's used is Delivery not authorized, message refused.

    When you create or modify the rule in PowerShell, you can specify the rejection reason text by using the RejectMessageReasonText parameter.

    IncidentReportContent One or more of the following values:
    • Sender
    • Recipients
    • Subject
    • Cc'd recipients (Cc)
    • Bcc'd recipients (Bcc)
    • Severity
    • Matching rules (RuleDetections)
    • False positive reports (FalsePositive)
    • Matching content (IdMatch)
    • Original mail (AttachOriginalMail)
    Specifies the original message properties to include in the incident report. You can choose to include any combination of these properties. In addition to the properties you specify, the message ID is always included. The available properties are:
    • Sender: The sender of the original message.
    • Recipients, Cc'd recipients, and Bcc'd recipients: All recipients of the message, or only the recipients in the Cc or Bcc fields. For each property, only the first 10 recipients are included in the incident report.
    • Subject: The Subject field of the original message.
    • Severity: The audit severity of the rule that was triggered. Message tracking logs include all the audit severity levels, and can be filtered by audit severity.

      In the EAC, if you clear the Audit this rule with severity level check box (in PowerShell, the SetAuditSeverity parameter value DoNotAudit), rule matches won't appear in the rule reports.

      If a message is processed by more than one rule, the highest severity is included in any incident reports.

    • Matching rules: The list of rules that the message triggered.
    • False positive reports: The false positive if the sender marked the message as a false positive for a Policy Tip.
    • Matching content: The sensitive information type detected, the exact matched content from the message, and the 150 characters before and after the matched sensitive information.
    • Original mail: The entire message that triggered the rule is attached to the incident report.

      In PowerShell, you specify multiple values separated by commas.

    MessageClassification Single message classification object In the EAC, you select from the list of available message classifications.

    In PowerShell, use the Get-MessageClassification cmdlet to see the message classification objects that are available.

    MessageHeaderField Single string Specifies the SMTP message header field to add, remove, or modify.

    The message header is a collection of required and optional header fields in the message. Examples of header fields are To, From, Received, and Content-Type. Official header fields are defined in RFC 5322. Unofficial header fields start with X- and are known as X-headers.

    NotificationMessageText Any combination of plain text, HTML tags, and keywords Specified the text to use in a recipient notification message.

    In addition to plain text and HTML tags, you can specify the following keywords that use values from the original message:

    • %%From%%
    • %%To%%
    • %%Cc%%
    • %%Subject%%
    • %%Headers%%
    • %%MessageDate%%
    OutboundConnector Single outbound connector Specifies the identity of outbound connector that's used to deliver messages. For more information about connectors, see Configure mail flow using connectors.

    In the EAC, you select the connector from a list.

    In PowerShell, use the Get-OutboundConnector cmdlet to see the connectors that are available.

    RMSTemplate Single Azure RMS template object Specifies the Azure Rights Management (Azure RMS) template that's applied to the message.

    In the EAC, you select the RMS template from a list.

    In PowerShell, use the Get-RMSTemplate cmdlet to see the RMS templates that are available.

    For more information about RMS in Microsoft 365 or Office 365, see What is Azure Information Protection?.

    SCLValue One of the following values:
    • Bypass spam filtering (-1)
    • Integers 0 through 9
    Specifies the spam confidence level (SCL) that's assigned to the message. A higher SCL value indicates that a message is more likely to be spam.
    String Single string Specifies the text that's applied to the specified message header field, NDR, or event log entry.

    In PowerShell, if the value contains spaces, enclose the value within quotation marks (").

    For more information

    Mail flow rules (transport rules) in Exchange Online

    Mail flow rule conditions and exceptions (predicates) in Exchange Online

    Mail flow rules (transport rules) in Exchange Online