Commands › Exchange Online

New-RetentionPolicyTag

Exchange Online ExchangeOnlineManagement New-*

Create a retention tag. For more information about retention tags, see Retention tags and retention policies in Exchange Server.

Quick start script

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

# 3. Make the change (dry run first)
New-RetentionPolicyTag -Name <String> -WhatIf
New-RetentionPolicyTag -Name <String>

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

Syntax — 2 parameter sets

RetentionPolicy (Default)

New-RetentionPolicyTag [-Name] <String>
 [-AddressForJournaling <RecipientIdParameter>]
 [-AgeLimitForRetention <EnhancedTimeSpan>]
 [-Comment <String>]
 [-Confirm]
 [-DomainController <Fqdn>]
 [-IsDefaultAutoGroupPolicyTag]
 [-IsDefaultModeratedRecipientsPolicyTag]
 [-JournalingEnabled <Boolean>]
 [-LabelForJournaling <String>]
 [-LocalizedComment <MultiValuedProperty>]
 [-LocalizedRetentionPolicyTagName <MultiValuedProperty>]
 [-MessageClass <String>]
 [-MessageFormatForJournaling <JournalingFormat>]
 [-MustDisplayCommentEnabled <Boolean>]
 [-RetentionAction <RetentionAction>]
 [-RetentionEnabled <Boolean>]
 [-RetentionId <Guid>]
 [-SystemTag <Boolean>]
 [-Type <ElcFolderType>]
 [-WhatIf]
 [<CommonParameters>]

UpgradeManagedFolder

New-RetentionPolicyTag [-Name] <String>
 [-ManagedFolderToUpgrade <ELCFolderIdParameter>]
 [-Comment <String>]
 [-Confirm]
 [-DomainController <Fqdn>]
 [-IsDefaultAutoGroupPolicyTag]
 [-IsDefaultModeratedRecipientsPolicyTag]
 [-LocalizedComment <MultiValuedProperty>]
 [-LocalizedRetentionPolicyTagName <MultiValuedProperty>]
 [-MustDisplayCommentEnabled <Boolean>]
 [-SystemTag <Boolean>]
 [-Type <ElcFolderType>]
 [-WhatIf]
 [<CommonParameters>]

Parameters (22)

Parameter	Type	Required	What it controls
-Name	String	yes	The Name parameter specifies the name of the tag.
-AddressForJournaling	RecipientIdParameter		This parameter is reserved for internal Microsoft use.
-AgeLimitForRetention	EnhancedTimeSpan		The AgeLimitForRetention parameter specifies the age at which retention is enforced on an item. The age limit corresponds to the number of days from the date the item was delivered, or the date an item was created if...
-Comment	String		The Comment parameter specifies a comment for the tag.
-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.
-DomainController	Fqdn		This parameter is available only in on-premises Exchange.
-IsDefaultAutoGroupPolicyTag	SwitchParameter		This parameter is available only in the cloud-based service.
-IsDefaultModeratedRecipientsPolicyTag	SwitchParameter		This parameter is available only in the cloud-based service.
-JournalingEnabled	Boolean		This parameter is reserved for internal Microsoft use.
-LabelForJournaling	String		This parameter is reserved for internal Microsoft use.
-LocalizedComment	MultiValuedProperty		The LocalizedComment parameter specifies localized comments and their languages. When the user's language setting matches a language specified for this parameter, Microsoft Outlook and Outlook on the web display the...
-LocalizedRetentionPolicyTagName	MultiValuedProperty		The LocalizedRetentionPolicyTagName parameter specifies localized tag names and their languages. When the user's language setting matches a language specified for this parameter, Outlook and Outlook on the web...
-ManagedFolderToUpgrade	ELCFolderIdParameter		This parameter is available only in on-premises Exchange.
-MessageClass	String		The MessageClass parameter specifies the message type to which the tag applies. If not specified, the default value is set to \*.
-MessageFormatForJournaling	JournalingFormat		This parameter is reserved for internal Microsoft use.
-MustDisplayCommentEnabled	Boolean		The MustDisplayCommentEnabled parameter specifies whether the comment can be hidden. The default value is $true.
-RetentionAction	RetentionAction		The RetentionAction parameter specifies the action for the retention policy. Valid values are:
-RetentionEnabled	Boolean		The RetentionEnabled parameter specifies whether the tag is enabled. When set to $false, the tag is disabled, and no retention action is taken on messages that have the tag applied.
-RetentionId	Guid		The RetentionId parameter specifies an alternate tag ID to make sure the retention tag found on mailbox items tagged in an on-premises deployment matches the tag when the mailbox is moved to the cloud, or mailbox...
-SystemTag	Boolean		The SystemTag parameter specifies that the tag is created for internal Exchange functionality.
-Type	ElcFolderType		The Type parameter specifies the type of retention tag being created. Valid values include:
-WhatIf	SwitchParameter		The WhatIf switch shows what the command does without making any changes. You don't need to specify a value with this switch.

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