Set-RetentionPolicyTag
This cmdlet is available in on-premises Exchange and in the cloud-based service. Some parameters and settings might be exclusive to one environment or the other.
Use the Set-RetentionPolicyTag cmdlet to modify the properties of a retention tag.
For more information about retention tags, see Retention tags and retention policies in Exchange Server.
For information about the parameter sets in the Syntax section below, see Exchange cmdlet syntax.
Syntax
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>]
Description
Retention tags are used to apply message retention settings to folders and items in a mailbox.
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
Set-RetentionPolicyTag "AllUsers-DeletedItems" -Comment "Items in the Deleted Items folder are automatically deleted in 120 days"
This example changes the comment for the AllUsers-DeletedItems retention policy tag.
Example 2
Set-RetentionPolicyTag -Mailbox "Terry Adams" -OptionalInMailbox "ProjectA","ProjectB"
This example makes optional retention tags available to user Terry Adams using the Mailbox and OptionalInMailbox parameters.
Parameters
-AddressForJournaling
Applicable: Exchange Server 2010
This parameter is available only in Exchange Server 2010.
This parameter is reserved for internal Microsoft use.
Parameter properties
| Type: | RecipientIdParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
Identity
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-AgeLimitForRetention
Applicable: Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Server SE, Exchange Online
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 it wasn't delivered. If this parameter isn't present and the RetentionEnabled parameter is set to $true, an error is returned.
Parameter properties
| Type: | EnhancedTimeSpan |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
Identity
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Comment
Applicable: Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Server SE, Exchange Online
The Comment parameter specifies a comment for the retention policy tag.
Parameter properties
| Type: | String |
| 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 |
-Confirm
Applicable: Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Server SE, Exchange Online
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 |
-DomainController
Applicable: Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Server SE
This parameter is available only in on-premises Exchange.
The DomainController parameter specifies the domain controller that's used by this cmdlet to read data from or write data to Active Directory. You identify the domain controller by its fully qualified domain name (FQDN). For example, dc01.contoso.com.
Parameter properties
| Type: | Fqdn |
| 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 |
-Force
Applicable: Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Server SE, Exchange Online
The Force switch hides warning or confirmation messages. You don't need to specify a value with this switch.
Use this switch to hide the confirmation prompt when you use the RetentionId parameter.
Parameter properties
| Type: | SwitchParameter |
| 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 |
-Identity
Applicable: Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Server SE, Exchange Online
The Identity parameter specifies the name, distinguished name (DN), or GUID of the retention policy tag to be modified.
Parameter properties
| Type: | RetentionPolicyTagIdParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
Identity
| Position: | 1 |
| Mandatory: | True |
| Value from pipeline: | True |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
-JournalingEnabled
Applicable: Exchange Server 2010
This parameter is available only in Exchange Server 2010.
This parameter is reserved for internal Microsoft use.
Parameter properties
| Type: | Boolean |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
Identity
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-LabelForJournaling
Applicable: Exchange Server 2010
This parameter is available only in Exchange Server 2010.
This parameter is reserved for internal Microsoft use.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
Identity
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-LegacyManagedFolder
Applicable: Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Server SE, Exchange Online
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 to create retention tags based on existing managed folders to migrate users from managed folder mailbox policies to retention policies.
Parameter properties
| Type: | ELCFolderIdParameter |
| 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 |
-LocalizedComment
Applicable: Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Server SE, Exchange Online
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.
Parameter properties
| Type: | MultiValuedProperty |
| 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 |
-LocalizedRetentionPolicyTagName
Applicable: Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Server SE, Exchange Online
The LocalizedRetentionPolicyTagName parameter specifies a localized name for the retention policy tag. This name is displayed in Outlook based on the user's locale.
Parameter properties
| Type: | MultiValuedProperty |
| 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 |
-Mailbox
Applicable: Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Server SE, Exchange Online
The Mailbox parameter specifies a mailbox for assigning opt-in tags. You can use any value that uniquely identifies the mailbox. For example:
- Name
- Alias
- Distinguished name (DN)
- Canonical DN
- Domain\Username
- Email address
- GUID
- LegacyExchangeDN
- SamAccountName
- User ID or user principal name (UPN)
You must use this parameter with the OptionalInMailbox parameter.
Parameter properties
| Type: | MailboxIdParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
MailboxTask
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-MessageClass
Applicable: Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Server SE, Exchange Online
The MessageClass parameter specifies the message type to which the tag applies. If not specified, the default value is set to *.
With the exception of a default policy tag (DPT) for voicemail, Exchange doesn't support retention tags for different message types. Only tags with a MessageClass of * are supported and they apply to all message types.
To create a DPT for voice mail messages, set the MessageClass parameter to voicemail and the Type parameter to All.
A DPT for voice mail messages applies only to Microsoft Exchange Unified Messaging voice mail messages (identified by the PR_MESSAGE_CLASS MAPI property value IPM.Note.Microsoft.Voicemail*).
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
Identity
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-MessageFormatForJournaling
Applicable: Exchange Server 2010
This parameter is available only in Exchange Server 2010.
This parameter is reserved for internal Microsoft use.
Parameter properties
| Type: | JournalingFormat |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
Identity
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-MustDisplayCommentEnabled
Applicable: Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Server SE, Exchange Online
The MustDisplayCommentEnabled parameter specifies whether the comment can be hidden. The default value is $true.
Parameter properties
| Type: | Boolean |
| 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 |
-Name
Applicable: Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Server SE, Exchange Online
The Name parameter specifies the name of the retention policy tag.
Parameter properties
| Type: | String |
| 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 |
-OptionalInMailbox
Applicable: Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Server SE, Exchange Online
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 policy applied to the specified mailbox. You can specify multiple personal tags separated by commas.
Parameter properties
| Type: | RetentionPolicyTagIdParameter[] |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
MailboxTask
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-RetentionAction
Applicable: Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Server SE, Exchange Online
The RetentionAction parameter specifies the action for the retention policy. Valid values are:
- DeleteAndAllowRecovery: Deletes a message and allows recovery from the Recoverable Items folder.
- MarkAsPastRetentionLimit: Messages are marked as past the retention limit.
- MoveToArchive: Moves a message to the user's archive mailbox. You can use this action for retention tags of type All, Personal, and RecoverableItems.
- PermanentlyDelete: Permanently deletes a message. A message that is permanently deleted can't be recovered using the Recoverable Items folder. Permanently deleted messages aren't returned in a Discovery search, unless litigation hold is enabled for the mailbox.
The MoveToDeletedItems and MoveToFolder actions are available, but don't work. These actions are available for upgrades from messaging records management (MRM) 1.0 (managed folders) to MRM 2.0 (retention policies). MRM 2.0 was introduced in Exchange 2010 Service Pack 1 (SP1).
If this parameter isn't present and the RetentionEnabled parameter is set to $true, an error is returned.
Parameter properties
| Type: | RetentionAction |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
Identity
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-RetentionEnabled
Applicable: Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Server SE, Exchange Online
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.
Messages with a disabled tag are still considered tagged, so any default policy tags in the user's retention policy aren't applied to such messages.
When you set the RetentionEnabled parameter to $false, the retention period for the tag is shown as Never. Users might apply this tag to items that they want to indicate should never be deleted or should never be moved to the archive. Enabling the tag later might result in unintentional deletion or archiving of items. To avoid this situation, if a retention policy is disabled temporarily, it might be advisable to change the name of that tag so that users are discouraged from using it, such as DISABLED_<Original Name>.
Parameter properties
| Type: | Boolean |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
Identity
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-RetentionId
Applicable: Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Server SE, Exchange Online
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 organization (for example, in a cross-forest deployment or in a cross-premises deployment, when a mailbox is moved from an on-premises Exchange server to the cloud, or a cloud-based mailbox is moved to an on-premises Exchange server).
Typically, you don't need to specify or modify the RetentionId parameter for a retention tag. This parameter is populated automatically when importing retention tags in a cross-forest or cross-premises deployment.
Parameter properties
| Type: | Guid |
| 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 |
-SystemTag
Applicable: Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Server SE, Exchange Online
The SystemTag parameter specifies whether the retention policy tag is created for internal Exchange functionality.
Parameter properties
| Type: | Boolean |
| 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 |
-WhatIf
Applicable: Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Server SE, Exchange Online
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.
Inputs
Input types
To see the input types that this cmdlet accepts, see Cmdlet Input and Output Types. If the Input Type field for a cmdlet is blank, the cmdlet doesn't accept input data.
Outputs
Output types
To see the return types, which are also known as output types, that this cmdlet accepts, see Cmdlet Input and Output Types. If the Output Type field is blank, the cmdlet doesn't return data.