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 Lotte.Vetler@office365itpros.com -Recipients Flayosc@outlook.com -SendReportTo Jim.Flynn@office365itpros.com -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 Lotte.Vetler@office365itpros.com -Recipients Flayosc@outlook.com -SendReportTo Jim.Flynn@office365itpros.com -TransportRules -UnifiedDlpRules

Server                                  MessageId
------                                  ---------
PAXPR04MB8095.EURPRD04.PROD.OUTLOOK.COM 626b8a86-c262-4457-911b-641a027989d7@DB9PR04MB8445.eurprd04.prod.outlook.com

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.

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.