Add retention tags to or remove retention tags from a retention policy in Exchange Online


Please refer to the Microsoft 365 security center and the Microsoft Purview compliance portal for Exchange security and compliance features. They are no longer available in the new Exchange admin center.


To proactively retain or delete mailbox content for information governance in Microsoft 365, we recommend that you use Microsoft 365 retention policies and retention labels from the Microsoft Purview compliance portal, instead of messaging records management that's described on this page. However, you should continue using messaging records management to move messages to archive mailboxes.

If you currently use messaging records management, this older feature will continue to work side-by-side with retention policies and retention labels. However, we recommend that going forward, you use Microsoft 365 retention policies and retention labels instead. They provide you with a single mechanism to centrally manage both retention and deletion of content across Microsoft 365.

You can add retention tags to a retention policy when the policy is created or anytime thereafter. For details about how to create a retention policy, including how to simultaneously add retention tags, see Create a Retention Policy.

A retention policy can contain the following retention tags:

  • One or more retention policy tags (RPTs) for supported default folders

  • One default policy tag (DPT) with the Move item to archive (compliance portal) or Move to Archive (Classic EAC) action

  • One DPT with the Delete and allow recovery or Permanently delete actions

  • One DPT for voice mail

  • Any number of personal tags

For more information about retention tags, see Retention tags and retention policies.

What do you need to know before you begin?

  • Estimated time to completion: 10 minutes.

  • You need to be assigned permissions before you can perform this procedure or procedures. To see what permissions you need, see the "Messaging records management" entry in the Feature permissions in Exchange Online topic.

  • Configuration to add or remove retention tags is in the Microsoft Purview compliance portal .

  • Retention tags aren't applied to a mailbox until they're linked to a retention policy and the Managed Folder Assistant processes the mailbox. Use the Start-ManagedFolderAssistant cmdlet to manually trigger the assistant to process a specified mailbox.


Having problems? Ask for help in the Exchange forums. Visit the forums at Exchange Online or Exchange Online Protection.

Use the Microsoft Purview compliance portal to add or remove retention tags

  1. Sign in to the Microsoft Purview compliance portal and navigate to Solutions > Data lifecycle management > Exchange (legacy) > MRM Retention policies.

  2. In the list view, select the retention policy to which you want to add retention tags, and then select Edit.

  3. On the Configure your policy page, use the following options:

    • To add and remove retention tags to and from the retention policy: Select + Add tag, and on the Choose retention tags pane, you can select new retention tags and remove already selected retention tags. When the required retention tags are selected, select Add.

    • To just remove retention tags: In the view list of retention tags, use the Delete icon for a retention tag that you want to remove.

Use Exchange Online PowerShell to add or remove retention tags

The following example adds the retention tags VPs-Default, VPs-Inbox, and VPs-DeletedItems to the retention policy RetPolicy-VPs, which doesn't already have retention tags linked to it:


If the policy has retention tags linked to it, this command replaces the existing tags.

Set-RetentionPolicy -Identity "RetPolicy-VPs" -RetentionPolicyTagLinks "VPs-Default","VPs-Inbox","VPs-DeletedItems"

The following example adds the retention tag VPs-DeletedItems to the retention policy RetPolicy-VPs, which already has other retention tags linked to it:

$TagList = (Get-RetentionPolicy "RetPolicy-VPs").RetentionPolicyTagLinks
$TagList.Add((Get-RetentionPolicyTag 'VPs-DeletedItems').DistinguishedName)
Set-RetentionPolicy "RetPolicy-VPs" -RetentionPolicyTagLinks $TagList

The following example removes the retention tag VPs-Inbox from the retention policy RetPolicy-VPs:

$TagList = (Get-RetentionPolicy "RetPolicy-VPs").RetentionPolicyTagLinks
$TagList.Remove((Get-RetentionPolicyTag 'VPs-Inbox').DistinguishedName)
Set-RetentionPolicy "RetPolicy-VPs" -RetentionPolicyTagLinks $TagList

For detailed syntax and parameter information, see set-RetentionPolicy and get-RetentionPolicy.

How do you know this worked?

To verify that you have successfully added or removed a retention tag from a retention policy, use the get-RetentionPolicy cmdlet to verify the RetentionPolicyTagLinks property.

This example uses the Get-RetentionPolicy cmdlet to retrieve retention tags added to the Default MRM Policy and pipes them to the Format-Table cmdlet to output only the name property of each tag.

(Get-RetentionPolicy "Default MRM Policy").RetentionPolicyTagLinks | Format-Table name