Commands › Exchange Online

New-RetentionComplianceRule

Exchange Online ExchangeOnlineManagement New-*

For more information, see Security & Compliance PowerShell. Use the New-RetentionComplianceRule cmdlet to create new retention rules in the Microsoft Purview compliance portal.

Quick start script

# New-RetentionComplianceRule — quick start (serv365.ai)
# 1. Connect (app-only shown; interactive: omit the certificate parameters)
Connect-ExchangeOnline -CertificateThumbprint $thumb -AppId $appId -Organization $org

# 2. Capture the current state first — you cannot roll back what you never recorded
$before = Get-RetentionComplianceRule
$before | Format-List

# 3. Make the change (dry run first)
New-RetentionComplianceRule -Name <String> -ApplyComplianceTag <String> -Policy <PolicyIdParameter> -WhatIf
New-RetentionComplianceRule -Name <String> -ApplyComplianceTag <String> -Policy <PolicyIdParameter>

# 4. Verify and diff
$after = Get-RetentionComplianceRule
Compare-Object ($before | Out-String) ($after | Out-String)

Syntax — 3 parameter sets

ComplianceTag

New-RetentionComplianceRule -ApplyComplianceTag <String> -Policy <PolicyIdParameter>
 [-ContentContainsSensitiveInformation <PswsHashtable[]>]
 [-Confirm]
 [-ContentMatchQuery <String>]
 [-ExpirationDateOption <String>]
 [-IRMRiskyUserProfiles <String>]
 [-MachineLearningModelIDs <MultiValuedProperty>]
 [-PriorityCleanup]
 [-RetentionComplianceAction <String>]
 [-WhatIf]
 [<CommonParameters>]

Default

New-RetentionComplianceRule [-Name] <String> -Policy <PolicyIdParameter>
 [-Comment <String>]
 [-ExcludedItemClasses <MultiValuedProperty>]
 [-RetentionDuration <Unlimited>]
 [-RetentionDurationDisplayHint <HoldDurationHint>]
 [-Confirm]
 [-ContentMatchQuery <String>]
 [-ExpirationDateOption <String>]
 [-PriorityCleanup]
 [-RetentionComplianceAction <String>]
 [-WhatIf]
 [<CommonParameters>]

PublishComplianceTag

New-RetentionComplianceRule -Policy <PolicyIdParameter> -PublishComplianceTag <String>
 [-Confirm]
 [-ExpirationDateOption <String>]
 [-PriorityCleanup]
 [-RetentionComplianceAction <String>]
 [-WhatIf]
 [<CommonParameters>]

Parameters (17)

Parameter	Type	Required	What it controls
-Name	String	yes	The Name parameter specifies a unique name for the retention rule. If the value contains spaces, enclose the value in quotation marks.
-ApplyComplianceTag	String	yes	The ApplyComplianceTag parameter specifies the label that's applied to email messages or documents by the rule (which affects how long the content is retained). A valid value for this parameter is the name of an...
-Policy	PolicyIdParameter	yes	The Policy parameter specifies the policy to contain the rule.
-PriorityCleanup	SwitchParameter		The PriorityCleanup switch specifies whether to create a rule associated with a Priority cleanup policy. You don't need to specify a value with this switch.
-PublishComplianceTag	String	yes	The PublishComplianceTag parameter specifies the label that's published for the rule, which makes the label visible to users in apps (for example, Outlook, SharePoint, and OneDrive). A valid value for this parameter...
-Comment	String		The Comment parameter specifies an optional comment. If you specify a value that contains spaces, enclose the value in quotation marks ("), for example: "This is an admin note".
-Confirm	SwitchParameter		The Confirm switch specifies whether to show or hide the confirmation prompt. How this switch affects the cmdlet depends on whether the cmdlet requires confirmation before proceeding.
-ContentContainsSensitiveInformation	PswsHashtable[]		The ContentContainsSensitiveInformation parameter specifies a condition for the rule that's based on a sensitive information type match in content. The rule is applied to content that contains the specified sensitive...
-ContentMatchQuery	String		The ContentMatchQuery parameter specifies a content search filter.
-ExcludedItemClasses	MultiValuedProperty		The ExcludedItemClasses parameter specifies the types of messages to exclude from the rule. You can use this parameter only to exclude items from a hold policy, which excludes the specified item class from being...
-ExpirationDateOption	String		The ExpirationDateOption parameter specifies whether the expiration date is calculated from the content creation date or last modification date. Valid values are:
-IRMRiskyUserProfiles	String		{{ Fill IRMRiskyUserProfiles Description }}
-MachineLearningModelIDs	MultiValuedProperty		This parameter is reserved for internal Microsoft use.
-RetentionComplianceAction	String		The RetentionComplianceAction parameter specifies the retention action for the rule. Valid values are:
-RetentionDuration	Unlimited		The RetentionDuration parameter specifies the hold duration for the retention rule. Valid values are:
-RetentionDurationDisplayHint	HoldDurationHint		The RetentionDurationDisplayHint parameter specifies the units that are used to display the retention duration in the Microsoft Purview compliance portal. Valid values are:
-WhatIf	SwitchParameter		The WhatIf switch doesn't work in Security & Compliance PowerShell.

Reference facts derived from Microsoft documentation, © Microsoft, licensed CC BY 4.0; restructured with original guidance by serv365.ai.