Get to know the Test-Message cmdlet

Exchange 2010 includes a little known cmdlet called Test-Message.  This cmdlet is used to troubleshoot the impact of Inbox rules on a message and gather detailed information about how rules are processing it.  It's also useful for testing the flow of moderated messages and to see the affects of large distribution group expansion without actually sending a message.

The RTM version of Test-Message is documented at http://technet.microsoft.com/en-us/library/dd298101(EXCHG.140).aspx, but there are a couple of additional parameters added in Exchange 2010 SP1 that are not listed there.  The purpose of this article is to show you how to configure the cmdlet and give examples its use.

To use the Test-Message cmdlet, you must add a user account or security group to the "Support Diagnostics" RBAC role in Exchange 2010.  You do this from the Exchange Management Shell by running the following command:

New-ManagementRoleAssignment -Role "Support Diagnostics" -SecurityGroup "Organization Management"

The command above adds the Exchange 2010 Organization Management group to the Support Diagnostics RBAC role.  If you want to add the role to an individual user, use the following command:

New-ManagementRoleAssignment -Role "Support Diagnostics" -User Jeff

Note that the added user must close and restart EMS to see the new cmdlet, since access to cmdlets is granted by RBAC when EMS is started.  You can find out which users have the Support Diagnostics role assigned to them by running the following command:

Get-ManagementRoleAssignment -Role "Support Diagnostics"

Now that we have the access to the Test-Message cmdlet through RBAC, let's see what we can do with it.  The examples below use the Exchange 2010 SP1 version of the cmdlet, which includes two additional non-documented parameters, -Arbitration (optional) and -InboxRules (required).

The simplest test would be:

Test-Message -Sender amy@contoso.com -Recipients jason@contoso.com -InboxRules:$false -SendReportTo jeff@contoso.com

This test will send a system generated message from Amy's mailbox to Jason's mailbox, bypassing Jason's Inbox rules, and then send the resulting report to Jeff's mailbox.  The report looks like this:

Here we can see that the message originated from Amy's Inbox, it evaluated Jeff's Inbox rules, displays the SCL Junk Threshold, and tells you the target folder for the message after the rules have run.  This is an easy way to troubleshoot messages that are deleted or delivered to another folder other than the Inbox.

It's important to note that the Sender parameter can be any SMTP email address, even an external address.  This is useful for testing various rule behaviors.

Note that the message also includes two attachments: mailbox-rules.xml and automatic-reply-history.xml.  Mailbox-rules.xml contains an export of all the rules for the target mailbox.  This can be used to backup the Inbox rule set and/or export to another user's mailbox.  Automatic-reply-history.xml which lists all the recipients where an OOF message fired.

By default, Test-Message adds the header, X-MS-Exchange-Organization-Test-Message: Supress to the message (and yes, "Supress" is mispelled that way).  This header causes Exchange to delete the message before it is delivered to the recipient mailbox.  If you want the message to be delivered to the recipient add the -DeliverMessage parameter.  An Exchange Diagnostic Message will then be delivered with the text, "This message was generated by an Exchange administrator. You can ignore this message, unless your administrator has requested otherwise."

See Tom Kern's article, Test-Message Improvements in Exchange 2010 Sp1 for even more info on the Test-Message cmdlet.