Test-Message
This cmdlet is functional only in the cloud-based service.
Use the Test-Message cmdlet to simulate and report on the effects of mail flow rules (transport rules) and unified DLP rules on test email messages. Because this cmdlet introduces email into the DLP evaluation pipeline, actions such as Block, Moderate, etc. can take place on the test message. Related notifications are also sent to any configured recipients.
For information about the parameter sets in the Syntax section below, see Exchange cmdlet syntax.
Syntax
TransportRules
Test-Message
-Recipients <ProxyAddressCollection>
-SendReportTo <RecipientIdParameter>
[-TransportRules]
[-Confirm]
[-Force]
[-MessageFileData <Byte[]>]
[-Sender <SmtpAddress>]
[-UnifiedDlpRules]
[-WhatIf]
[<CommonParameters>]
UnifiedDLPRules
Test-Message
-Recipients <ProxyAddressCollection>
-SendReportTo <RecipientIdParameter>
[-UnifiedDlpRules]
[-Confirm]
[-Force]
[-MessageFileData <Byte[]>]
[-Sender <SmtpAddress>]
[-WhatIf]
[<CommonParameters>]
Description
You need to be assigned permissions before you can run this cmdlet. Although this article lists all parameters for the cmdlet, you might not have access to some parameters if they aren't included in the permissions assigned to you. To find the permissions required to run any cmdlet or parameter in your organization, see Find the permissions required to run any Exchange cmdlet.
Examples
Example 1
$data = [System.IO.File]::ReadAllBytes('C:\Data\test.eml')
Test-Message -MessageFileData $data -Sender megan@contoso.com -Recipients adele@contoso.com -SendReportTo admin@contoso.com -TransportRules -UnifiedDlpRules
This example uses the test.eml message file at C:\Data to test mail flow rules and unified DLP rules for the sender megan@contoso.com to the recipient adele@contoso.com. The results report is sent to admin@contoso.com.
Parameters
-Confirm
Applicable: Exchange Server 2013, Exchange Online, Exchange Online Protection
The Confirm switch specifies whether to show or hide the confirmation prompt. How this switch affects the cmdlet depends on if the cmdlet requires confirmation before proceeding.
- Destructive cmdlets (for example, Remove-* cmdlets) have a built-in pause that forces you to acknowledge the command before proceeding. For these cmdlets, you can skip the confirmation prompt by using this exact syntax:
-Confirm:$false. - Most other cmdlets (for example, New-* and Set-* cmdlets) don't have a built-in pause. For these cmdlets, specifying the Confirm switch without a value introduces a pause that forces you acknowledge the command before proceeding.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | cf |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Force
Applicable: Exchange Online, Exchange Online Protection
The Force switch specifies whether to suppress warning or confirmation messages. You can use this switch to run tasks programmatically where prompting for administrative input is inappropriate. You don't need to specify a value with this switch.
Parameter properties
| Type: | SwitchParameter |
| Default value: | False |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-MessageFileData
Applicable: Exchange Online, Exchange Online Protection
The MessageFileData parameter specifies the .eml message file to test.
A valid value for this parameter requires you to read the file to a byte-encoded object using the following syntax: ([System.IO.File]::ReadAllBytes('<Path>\<FileName>')). You can use this command as the parameter value, or you can write the output to a variable ($data = [System.IO.File]::ReadAllBytes('<Path>\<FileName>')) and use the variable as the parameter value ($data).
Parameter properties
| Type: | Byte[] |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Recipients
Applicable: Exchange Online, Exchange Online Protection
The Recipients parameter specifies the recipient email address to use for the test message.
You can specify multiple email addresses separated by commas.
Parameter properties
| Type: | ProxyAddressCollection |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Sender
Applicable: Exchange Online, Exchange Online Protection
The Sender parameter specifies the sender email address to use for the test message.
Parameter properties
| Type: | SmtpAddress |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-SendReportTo
Applicable: Exchange Online, Exchange Online Protection
The SendReportTo parameter specifies the target email address for the command results.
Parameter properties
| Type: | RecipientIdParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-TransportRules
Applicable: Exchange Server 2013, Exchange Online, Exchange Online Protection
The TransportRules switch specifies that you want to test mail flow rules. You don't need to specify a value with this switch.
Parameter properties
| Type: | SwitchParameter |
| Default value: | False |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
TransportRules
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-UnifiedDlpRules
Applicable: Exchange Online, Exchange Online Protection
The UnifiedDlpRules switch specifies that you want to unified DLP rules. You don't need to specify a value with this switch.
Parameter properties
| Type: | SwitchParameter |
| Default value: | False |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
UnifiedDLPRules
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
TransportRules
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-WhatIf
Applicable: Exchange Server 2013, Exchange Online, Exchange Online Protection
The WhatIf switch simulates the actions of the command. You can use this switch to view the changes that would occur without actually applying those changes. You don't need to specify a value with this switch.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | wi |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.