How to Run the Test-Message Cmdlet

Use Test-Message to Validate Exchange Online Rules Processing Against Email

Announced in Microsoft 365 message center notification MC503297 (26 January 2023, roadmap item 100494), the Exchange Online Test-Message cmdlet is now generally available. The purpose of the cmdlet is very simple: it tests the path of a message through the rules applied by the Exchange Online transport service to reveal what actions those rules take. The intention is to help tenant administrators understand why a rule doesn’t function as expected without having to ask Microsoft support for assistance.

The set of tested rules include:

  • Exchange Online transport rules (ETRs, also known as mail flow rules). Up to 300 ETRs can exist in an Exchange Online organization to do anything from automatically copying messages sent to a certain domain to applying disclaimers to outbound messages (here’s an example of using an ETR to apply a special disclaimer for calendar meeting notifications.
  • Rules created to enforce actions from Microsoft 365 DLP policies. For example, to stop people sharing confidential information with external recipients.
  • Rules created to apply Microsoft Purview retention or sensitivity labels.

Over time, my small tenant has accumulated 25 different transport rules plus a set of DLP policies and some auto-label policies. The permutations and combinations involved in rule processing within the transport service can become very complex indeed. ETRs have a priority order to determine how the transport service runs the rules. A rule can force processing to stop if necessary. DLP policies run after ETRs, and auto-labeling then kicks in if a message is allowed to proceed by ETRs and DLP.

Test-Message Examples

Here’s a simple example of the Test-Message cmdlet in action:

Test-Message -Sender -Recipients -SendReportTo -TransportRules -UnifiedDlpRules

This kind of test runs rules against a sample message. It can only check the message sender and recipients, so apart from cycling through all the available rules, it’s not a very extensive test.

A slightly more complicated example uses a test message that I created with Outlook and saved as a message file. Using a test message makes sure that rules run against precisely the kind of traffic that you expect the rule to detect and process. For instance, you might want to include some specific keywords in the message subject or body text, or an attachment of a certain type.

To pass the message to Test-Message, it must first be encoded and stored in a variable, which is then specified in the MessageFileData parameter.

$EncodedText = ([System.IO.File]::ReadAllBytes('c:\temp\TestMessage.msg'))

Test-Message -MessageFileData  $EncodedText -Sender -Recipients -SendReportTo -TransportRules -UnifiedDlpRules

Server                                  MessageId
------                                  ---------

The server information reported by the cmdlet is the Exchange Online mailbox server where the transport rules run. Given the massive pool of Exchange Online servers, it’s likely that Test-Message will use a different server each time it runs.

Test-Message Output

The output is in messages delivered to the address specified in the SendReportTo parameter for each type of rule processed by the test. In my case, the test generated three messages (DLP, auto-label, and ETR). Figure 1 shows the results for the ETR test. We can see that a match occurred for the Office 365 Message Encryption for selected external domains rule, which executed two actions to apply rights management protection to the message with custom branding. After executing the two actions, the transport service stopped processing further rules because the rule settings forced an exit.

Exchange transport rules report generated by the Test-Message cmdlet
Figure 1: Exchange transport rules report generated by the Test-Message cmdlet

Steps to Follow for Rule Creation

Nice as it is to have a cmdlet to help test rules processing, it won’t replace the simple rules that experienced administrators follow when setting up new ETRs or DLP policies.

  • Know what your rule should do (the actions).
  • Know what conditions the rule needs to detect before it runs.
  • Know what exceptions (if any) exist.
  • Start with a simple rule and build complexity gradually.
  • Always ask if your rule is likely to interfere with another rule before enabling it. You might be able to make a small adjustment to an existing rule to do what you want instead of creating a brand-new rule.

The last point is the most important.

Insight like this doesn’t come easily. You’ve got to know the technology and understand how to look behind the scenes. Benefit from the knowledge and experience of the Office 365 for IT Pros team by subscribing to the best eBook covering Office 365 and the wider Microsoft 365 ecosystem.

4 Replies to “How to Run the Test-Message Cmdlet”

  1. Hello Tony,

    surely this is not the place to ask you a question about mail flow rules, but I’ll try anyway.
    I need to solve an issue in EAC Mail Flow Rules.
    I’ve a shared mailbox that has since 150 hundred of alias, and I receive on it more e-mails in a day.
    I need to create a simply rule that intercept the alias recipient name and add it in a disclaimer in e-mail body, so i.e. if a user write to the alias, I need that this discalimer will be append into the body of the e-mail:

    I tried using a solution like this, but I’m here to ask you if is it possible to generalize this solution.

    Thanks in advance, and sorry if this is not the best plce to ask you a support.

    Mauro Balsano

    1. Maybe try:

      1. Create a distribution list and include the shared mailbox in the list.
      2. Create a mail flow rule that looks for any mail sent to members of the distribution list. This should include all the aliases assigned to the shared mailbox.
      3. The rule action is to apply the disclaimer.

      1. Hello Tony,

        on first thanks for the reply.

        I followed you unitl step 2:
        – Apply this rule if *
        — The recipient si a member of ‘’

        So, the question is: which text do I need to append for the disclaimer for show the recipient alias name that has received e-mail?
        – Do the following *
        — Append and fall back to action if the disclaimer can’t be inserted

        Thanks again.

        Mauro Balsano

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.