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:
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.
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.
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.
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 microsoft@mydomain.com 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 customer01@mydomain.com, I need that this discalimer will be append into the body of the e-mail:
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.
I followed you unitl step 2:
– Apply this rule if *
— The recipient si a member of ‘microsoftdistlist@mydomain.com’
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
{"id":null,"mode":"button","open_style":"in_modal","currency_code":"EUR","currency_symbol":"\u20ac","currency_type":"decimal","blank_flag_url":"https:\/\/office365itpros.com\/wp-content\/plugins\/tip-jar-wp\/\/assets\/images\/flags\/blank.gif","flag_sprite_url":"https:\/\/office365itpros.com\/wp-content\/plugins\/tip-jar-wp\/\/assets\/images\/flags\/flags.png","default_amount":100,"top_media_type":"featured_image","featured_image_url":"https:\/\/office365itpros.com\/wp-content\/uploads\/2022\/11\/cover-141x200.jpg","featured_embed":"","header_media":null,"file_download_attachment_data":null,"recurring_options_enabled":true,"recurring_options":{"never":{"selected":true,"after_output":"One time only"},"weekly":{"selected":false,"after_output":"Every week"},"monthly":{"selected":false,"after_output":"Every month"},"yearly":{"selected":false,"after_output":"Every year"}},"strings":{"current_user_email":"","current_user_name":"","link_text":"Virtual Tip Jar","complete_payment_button_error_text":"Check info and try again","payment_verb":"Pay","payment_request_label":"Office 365 for IT Pros","form_has_an_error":"Please check and fix the errors above","general_server_error":"Something isn't working right at the moment. Please try again.","form_title":"Office 365 for IT Pros","form_subtitle":null,"currency_search_text":"Country or Currency here","other_payment_option":"Other payment option","manage_payments_button_text":"Manage your payments","thank_you_message":"Thank you for supporting the work of Office 365 for IT Pros!","payment_confirmation_title":"Office 365 for IT Pros","receipt_title":"Your Receipt","print_receipt":"Print Receipt","email_receipt":"Email Receipt","email_receipt_sending":"Sending receipt...","email_receipt_success":"Email receipt successfully sent","email_receipt_failed":"Email receipt failed to send. Please try again.","receipt_payee":"Paid to","receipt_statement_descriptor":"This will show up on your statement as","receipt_date":"Date","receipt_transaction_id":"Transaction ID","receipt_transaction_amount":"Amount","refund_payer":"Refund from","login":"Log in to manage your payments","manage_payments":"Manage Payments","transactions_title":"Your Transactions","transaction_title":"Transaction Receipt","transaction_period":"Plan Period","arrangements_title":"Your Plans","arrangement_title":"Manage Plan","arrangement_details":"Plan Details","arrangement_id_title":"Plan ID","arrangement_payment_method_title":"Payment Method","arrangement_amount_title":"Plan Amount","arrangement_renewal_title":"Next renewal date","arrangement_action_cancel":"Cancel Plan","arrangement_action_cant_cancel":"Cancelling is currently not available.","arrangement_action_cancel_double":"Are you sure you'd like to cancel?","arrangement_cancelling":"Cancelling Plan...","arrangement_cancelled":"Plan Cancelled","arrangement_failed_to_cancel":"Failed to cancel plan","back_to_plans":"\u2190 Back to Plans","update_payment_method_verb":"Update","sca_auth_description":"Your have a pending renewal payment which requires authorization.","sca_auth_verb":"Authorize renewal payment","sca_authing_verb":"Authorizing payment","sca_authed_verb":"Payment successfully authorized!","sca_auth_failed":"Unable to authorize! Please try again.","login_button_text":"Log in","login_form_has_an_error":"Please check and fix the errors above","uppercase_search":"Search","lowercase_search":"search","uppercase_page":"Page","lowercase_page":"page","uppercase_items":"Items","lowercase_items":"items","uppercase_per":"Per","lowercase_per":"per","uppercase_of":"Of","lowercase_of":"of","back":"Back to plans","zip_code_placeholder":"Zip\/Postal Code","download_file_button_text":"Download File","input_field_instructions":{"tip_amount":{"placeholder_text":"How much would you like to tip?","initial":{"instruction_type":"normal","instruction_message":"How much would you like to tip? Choose any currency."},"empty":{"instruction_type":"error","instruction_message":"How much would you like to tip? Choose any currency."},"invalid_curency":{"instruction_type":"error","instruction_message":"Please choose a valid currency."}},"recurring":{"placeholder_text":"Recurring","initial":{"instruction_type":"normal","instruction_message":"How often would you like to give this?"},"success":{"instruction_type":"success","instruction_message":"How often would you like to give this?"},"empty":{"instruction_type":"error","instruction_message":"How often would you like to give this?"}},"name":{"placeholder_text":"Name on Credit Card","initial":{"instruction_type":"normal","instruction_message":"Enter the name on your card."},"success":{"instruction_type":"success","instruction_message":"Enter the name on your card."},"empty":{"instruction_type":"error","instruction_message":"Please enter the name on your card."}},"privacy_policy":{"terms_title":"Terms and conditions","terms_body":null,"terms_show_text":"View Terms","terms_hide_text":"Hide Terms","initial":{"instruction_type":"normal","instruction_message":"I agree to the terms."},"unchecked":{"instruction_type":"error","instruction_message":"Please agree to the terms."},"checked":{"instruction_type":"success","instruction_message":"I agree to the terms."}},"email":{"placeholder_text":"Your email address","initial":{"instruction_type":"normal","instruction_message":"Enter your email address"},"success":{"instruction_type":"success","instruction_message":"Enter your email address"},"blank":{"instruction_type":"error","instruction_message":"Enter your email address"},"not_an_email_address":{"instruction_type":"error","instruction_message":"Make sure you have entered a valid email address"}},"note_with_tip":{"placeholder_text":"Your note here...","initial":{"instruction_type":"normal","instruction_message":"Attach a note to your tip (optional)"},"empty":{"instruction_type":"normal","instruction_message":"Attach a note to your tip (optional)"},"not_empty_initial":{"instruction_type":"normal","instruction_message":"Attach a note to your tip (optional)"},"saving":{"instruction_type":"normal","instruction_message":"Saving note..."},"success":{"instruction_type":"success","instruction_message":"Note successfully saved!"},"error":{"instruction_type":"error","instruction_message":"Unable to save note note at this time. Please try again."}},"email_for_login_code":{"placeholder_text":"Your email address","initial":{"instruction_type":"normal","instruction_message":"Enter your email to log in."},"success":{"instruction_type":"success","instruction_message":"Enter your email to log in."},"blank":{"instruction_type":"error","instruction_message":"Enter your email to log in."},"empty":{"instruction_type":"error","instruction_message":"Enter your email to log in."}},"login_code":{"initial":{"instruction_type":"normal","instruction_message":"Check your email and enter the login code."},"success":{"instruction_type":"success","instruction_message":"Check your email and enter the login code."},"blank":{"instruction_type":"error","instruction_message":"Check your email and enter the login code."},"empty":{"instruction_type":"error","instruction_message":"Check your email and enter the login code."}},"stripe_all_in_one":{"initial":{"instruction_type":"normal","instruction_message":"Enter your credit card details here."},"empty":{"instruction_type":"error","instruction_message":"Enter your credit card details here."},"success":{"instruction_type":"normal","instruction_message":"Enter your credit card details here."},"invalid_number":{"instruction_type":"error","instruction_message":"The card number is not a valid credit card number."},"invalid_expiry_month":{"instruction_type":"error","instruction_message":"The card's expiration month is invalid."},"invalid_expiry_year":{"instruction_type":"error","instruction_message":"The card's expiration year is invalid."},"invalid_cvc":{"instruction_type":"error","instruction_message":"The card's security code is invalid."},"incorrect_number":{"instruction_type":"error","instruction_message":"The card number is incorrect."},"incomplete_number":{"instruction_type":"error","instruction_message":"The card number is incomplete."},"incomplete_cvc":{"instruction_type":"error","instruction_message":"The card's security code is incomplete."},"incomplete_expiry":{"instruction_type":"error","instruction_message":"The card's expiration date is incomplete."},"incomplete_zip":{"instruction_type":"error","instruction_message":"The card's zip code is incomplete."},"expired_card":{"instruction_type":"error","instruction_message":"The card has expired."},"incorrect_cvc":{"instruction_type":"error","instruction_message":"The card's security code is incorrect."},"incorrect_zip":{"instruction_type":"error","instruction_message":"The card's zip code failed validation."},"invalid_expiry_year_past":{"instruction_type":"error","instruction_message":"The card's expiration year is in the past"},"card_declined":{"instruction_type":"error","instruction_message":"The card was declined."},"missing":{"instruction_type":"error","instruction_message":"There is no card on a customer that is being charged."},"processing_error":{"instruction_type":"error","instruction_message":"An error occurred while processing the card."},"invalid_request_error":{"instruction_type":"error","instruction_message":"Unable to process this payment, please try again or use alternative method."},"invalid_sofort_country":{"instruction_type":"error","instruction_message":"The billing country is not accepted by SOFORT. Please try another country."}}}},"fetched_oembed_html":false}
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 microsoft@mydomain.com 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 customer01@mydomain.com, I need that this discalimer will be append into the body of the e-mail:
I tried using a solution like this https://o365reports.com/2020/03/25/how-to-add-external-email-warning-message/, 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.
Regards,
Mauro Balsano
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.
Hello Tony,
on first thanks for the reply.
I followed you unitl step 2:
– Apply this rule if *
— The recipient si a member of ‘microsoftdistlist@mydomain.com’
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.
Regards,
Mauro Balsano
I don’t think you can insert the alias. That’s not one of the fields available for the transport service to insert. https://learn.microsoft.com/en-us/exchange/policy-and-compliance/mail-flow-rules/signatures?view=exchserver-2019