Commands › Exchange Online

New-ComplianceTag

Exchange Online ExchangeOnlineManagement New-*

For more information, see Security & Compliance PowerShell. Use the New-ComplianceTag cmdlet to create retention labels in the Microsoft Purview compliance portal. Retention labels apply retention settings to content.

Quick start script

# New-ComplianceTag — 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-ComplianceTag
$before | Format-List

# 3. Make the change (dry run first)
New-ComplianceTag -Name <String> -PriorityCleanup <SwitchParameter> -RetentionAction <String> -WhatIf
New-ComplianceTag -Name <String> -PriorityCleanup <SwitchParameter> -RetentionAction <String>

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

Syntax — 2 parameter sets

Default

New-ComplianceTag [-Name] <String>
 [-AutoApprovalPeriod <System.Int32>]
 [-Comment <String>]
 [-ComplianceTagForNextStage <String>]
 [-Confirm]
 [-EventType <ComplianceRuleIdParameter>]
 [-FilePlanProperty <String>]
 [-FlowId <System.Guid>]
 [-Force]
 [-IsRecordLabel <Boolean>]
 [-IsRecordUnlockedAsDefault <Boolean>]
 [-MultiStageReviewProperty <String>]
 [-Notes <String>]
 [-Regulatory <Boolean>]
 [-RetentionAction <String>]
 [-RetentionDuration <Unlimited>]
 [-RetentionType <String>]
 [-ReviewerEmail <SmtpAddress[]>]
 [-WhatIf]
 [<CommonParameters>]

PriorityCleanup

New-ComplianceTag [-Name] <String> -RetentionAction <String> -RetentionDuration <Unlimited> -RetentionType <String>
 -MultiStageReviewProperty <String> [-PriorityCleanup]
 [-Comment <String>]
 [-Confirm]
 [-Force]
 [-Notes <String>]
 [-WhatIf]
 [<CommonParameters>]

Parameters (20)

Parameter	Type	Required	What it controls
-Name	String	yes	The Name parameter specifies a unique name for the label. If the value contains spaces, enclose the value in quotation marks (").
-PriorityCleanup	SwitchParameter	yes	{{ Fill PriorityCleanup Description }}
-RetentionAction	String	yes	The RetentionAction parameter specifies the action for the label. Valid values are:
-RetentionDuration	Unlimited	yes	The RetentionDuration parameter specifies the number of days to retain the content. Valid values are:
-RetentionType	String	yes	The RetentionType parameter specifies whether the retention duration is calculated from the content creation date, tagged date, or last modification date. Valid values are:
-AutoApprovalPeriod	Int32		{{ Fill AutoApprovalPeriod Description }}
-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".
-ComplianceTagForNextStage	String		{{ Fill ComplianceTagForNextStage Description }}
-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.
-EventType	ComplianceRuleIdParameter		The EventType specifies the retention rule that's associated with the label. You can use any value that uniquely identifies the rule. For example:
-FilePlanProperty	String		The FilePlanProperty parameter specifies the file plan properties to include in the label. To view the file plan property names that you need to use in this parameter, run the following commands:
-FlowId	Guid		Note: This parameter is currently in Preview, is not available in all organizations, and is subject to change.
-Force	SwitchParameter		The Force switch hides warning or confirmation messages. You don't need to specify a value with this switch.
-IsRecordLabel	Boolean		The IsRecordLabel parameter specifies whether the label is a record label. Valid values are:
-IsRecordUnlockedAsDefault	Boolean		{{ Fill IsRecordUnlockedAsDefault Description }}
-MultiStageReviewProperty	String		The MultiStageReviewProperty parameter specifies the multi-stage review properties to include in the label. This parameter uses the following syntax:
-Notes	String		The Notes parameter specifies additional information about the object. If the value contains spaces, enclose the value in quotation marks (").
-Regulatory	Boolean		{{ Fill Regulatory Description }}
-ReviewerEmail	SmtpAddress[]		The ReviewerEmail parameter specifies the email address of a reviewer for Delete and KeepAndDelete retention actions. You can specify multiple email addresses separated by commas.
-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.