Commands › Exchange Online

Set-RetentionPolicyTag

Exchange Online ExchangeOnlineManagement Set-*

Modify the properties of a retention tag. For more information about retention tags, see Retention tags and retention policies in Exchange Server.

Quick start script

# Set-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)
Set-RetentionPolicyTag -Identity <RetentionPolicyTagIdParameter> -Mailbox <MailboxIdParameter> -WhatIf
Set-RetentionPolicyTag -Identity <RetentionPolicyTagIdParameter> -Mailbox <MailboxIdParameter>

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

Syntax — 2 parameter sets

Identity

Set-RetentionPolicyTag [-Identity] <RetentionPolicyTagIdParameter>
 [-AddressForJournaling <RecipientIdParameter>]
 [-AgeLimitForRetention <EnhancedTimeSpan>]
 [-Comment <String>]
 [-Confirm]
 [-DomainController <Fqdn>]
 [-Force]
 [-JournalingEnabled <Boolean>]
 [-LabelForJournaling <String>]
 [-LegacyManagedFolder <ELCFolderIdParameter>]
 [-LocalizedComment <MultiValuedProperty>]
 [-LocalizedRetentionPolicyTagName <MultiValuedProperty>]
 [-MessageClass <String>]
 [-MessageFormatForJournaling <JournalingFormat>]
 [-MustDisplayCommentEnabled <Boolean>]
 [-Name <String>]
 [-RetentionAction <RetentionAction>]
 [-RetentionEnabled <Boolean>]
 [-RetentionId <Guid>]
 [-SystemTag <Boolean>]
 [-WhatIf]
 [<CommonParameters>]

MailboxTask

Set-RetentionPolicyTag -Mailbox <MailboxIdParameter>
 [-Comment <String>]
 [-Confirm]
 [-DomainController <Fqdn>]
 [-Force]
 [-LegacyManagedFolder <ELCFolderIdParameter>]
 [-LocalizedComment <MultiValuedProperty>]
 [-LocalizedRetentionPolicyTagName <MultiValuedProperty>]
 [-MustDisplayCommentEnabled <Boolean>]
 [-Name <String>]
 [-OptionalInMailbox <RetentionPolicyTagIdParameter[]>]
 [-RetentionId <Guid>]
 [-SystemTag <Boolean>]
 [-WhatIf]
 [<CommonParameters>]

Parameters (23)

Parameter	Type	Required	What it controls
-Identity	RetentionPolicyTagIdParameter	yes	The Identity parameter specifies the name, distinguished name (DN), or GUID of the retention policy tag to be modified.
-Mailbox	MailboxIdParameter	yes	The Mailbox parameter specifies a mailbox for assigning opt-in tags. You can use any value that uniquely identifies the mailbox. For example:
-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 retention policy 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.
-Force	SwitchParameter		The Force switch hides warning or confirmation messages. You don't need to specify a value with this switch.
-JournalingEnabled	Boolean		This parameter is reserved for internal Microsoft use.
-LabelForJournaling	String		This parameter is reserved for internal Microsoft use.
-LegacyManagedFolder	ELCFolderIdParameter		The LegacyManagedFolder parameter specifies the name of a managed folder. The retention tag is created by using retention settings from the managed folder and its managed content settings. You can use this parameter...
-LocalizedComment	MultiValuedProperty		The LocalizedComment parameter specifies the localized comment and language for the retention policy tag. This comment is displayed in Microsoft Outlook based on the user's locale.
-LocalizedRetentionPolicyTagName	MultiValuedProperty		The LocalizedRetentionPolicyTagName parameter specifies a localized name for the retention policy tag. This name is displayed in Outlook based on the user's locale.
-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.
-Name	String		The Name parameter specifies the name of the retention policy tag.
-OptionalInMailbox	RetentionPolicyTagIdParameter[]		The OptionalInMailbox parameter is used with the Mailbox parameter to assign personal tags to the mailbox. You can use this parameter to make available to a user a personal tag that isn't assigned to the retention...
-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 ensure the retention tag found on mailbox items tagged in one Exchange organization matches the tag when the mailbox is moved to another Exchange...
-SystemTag	Boolean		The SystemTag parameter specifies whether the retention policy tag is created for internal Exchange functionality.
-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.