Need details on who and what are triggering your rules? There's a cmdlet for that!

Need to get a list of all messages that triggered a particular transport rule, or do you want to see all rules that have been triggered by a particular sender? This information can be easily found using the Get-MailDetailTransportRuleReport cmdlet. Looking past the name being much too long, this cmdlet can provide very insightful information about your transport rules.

What better way to show off this cmdlet than with examples. Here we go.

Example 1

We would like to see the details of all messages that have triggered a particular transport rule over the past seven days. Using the report Rule matches for mail in the portal, we can view details of these messages on a day by day bases only, not over a date range, which can be seen here.

We can accomplish this same search with PowerShell which of course is more powerful. For instance, PowerShell can show us details of all messages that triggered this particular rule over multiple days, where as the portal is limited to showing only a single day at a time.
Here’s what the PowerShell would look like to see which messages triggered a particular rule over the past seven days.

Get-MailDetailTransportRuleReport -TransportRule "Trigger on keyword" -StartDate (Get-Date).AddDays(-7) -EndDate (Get-Date) | Sort-Object Date | Select-Object Date, MessageID, SenderAddress, RecipientAddress, Subject, TransportRule -Unique | ft

The results are as follows, which show that two unique messages triggered this particular rule.

If you wanted to just get a count and not the message details, you could run the following.

(Get-MailDetailTransportRuleReport -TransportRule "Trigger on keyword" -StartDate (Get-Date).AddDays(-7) -EndDate (Get-Date) | Sort-Object Date | Select-Object Date, MessageID, SenderAddress, RecipientAddress, Subject, TransportRule -Unique).count

Example 2

Next we want to see what rules a particular sender has triggered. This search can’t be accomplished in the portal, but can be with PowerShell. We can search on a particular sender, or for both sender and transport rule to limit the results.

Below, I’m going to search only on a sender to see which of their messages triggered transport rules over the last seven days.

Get-MailDetailTransportRuleReport -SenderAddress joeuser@contoso.com -StartDate (Get-Date).AddDays(-7) -EndDate (Get-Date) | Sort-Object Date | Select-Object Date, MessageID, SenderAddress, RecipientAddress, Subject, TransportRule -Unique | ft

I can quickly see that there are four unique messages, each of which triggered at least one transport rule, some triggering more.

Example 3

We want to know how many rules a particular message triggered by searching based on the Message-ID. Again we are searching over the last seven days.

Get-MailDetailTransportRuleReport -MessageId "<270946a8-da91-4793-9570-b06e80473b86@mft.local>" -StartDate (Get-Date).AddDays(-7) -EndDate (Get-Date) | Sort-Object Date | Select-Object Date, SenderAddress, RecipientAddress, Subject, TransportRule -Unique | ft

Example 4

What outbound messages caused rules to trigger over the past seven days?

Get-MailDetailTransportRuleReport -Direction Outbound -StartDate (Get-Date).AddDays(-7) -EndDate (Get-Date) | Sort-Object Date | Select-Object Date, MessageID, SenderAddress, RecipientAddress, Subject, TransportRule -Unique | ft

Final comments

In addition to the criteria we looked at in the above examples, we can also search based on Recipient, MessageSize, Rule Action, and many others. These are all searches not possible through the Portal.

You’ll notice that in my above examples I used the –unique option. The Get-MailDetailTransportRuleReport will sometimes return duplicate values, and using –unique will filter these out.

As with all reporting there is some latency. Data aggregation will mostly be complete within 24-48 hours. Reports on data older than 7 days can be obtained through the portal, but these reports will take time to run (possibly up to a few hours). See Monitoring, reporting, and message tracing in Exchange Online. 

Finally, while this won’t be a cmdlet you’ll use daily, it is still one to keep in your troubleshooting arsenal as it provides very insightful data about your transport rules and what and who are triggering them.

Resources

Connect to Exchange Online PowerShell
Exchange Online cmdlets
Get-MailDetailTransportRuleReport

Comments

• Anonymous
  October 14, 2015
  Very handy! One issue I have run into is that the maximum pagesize of 5000 still is not enough. I have way more records than that. How can I download all of these messages without having to configure the -page parameter
• Anonymous
  October 23, 2015
  Hi Scott, as far as I know you'll need to use the -page parameter. You could write a script that uses a FOR loop that would loop through page numbers which would allow you to pull the data in one shot.