PowerShell cmdlets for retention policies and retention labels

Microsoft 365 licensing guidance for security & compliance.

Use the following sections to identify the main PowerShell cmdlets that are available for retention policies and retention labels that you might need for configuration at-scale, automated scripts, or advanced configuration scenarios. For the full list of cmdlets, see the policy-and-compliance-retention list from the PowerShell documentation.

Before you use these cmdlets, you must first connect to Security & Compliance PowerShell.

In the descriptions that follow, a policy for retention can refer to a retention policy (no labels), or a retention label policy. Each policy defines whether it's static or adaptive and the locations for the policy to be applied.

When you use retention policies, the policy requires one rule to complete the configuration, for example, a rule that defines the retention settings, such as retain for five years and then delete.

When you use retention labels, these contain the retention settings and their policies need different rules:

  • A retention label policy that you publish needs a rule that defines which labels should be displayed in apps.
  • An auto-apply retention label policy needs a rule that defines the label to apply and the conditions for applying the label.

Tip

If you're not an E5 customer, use the 90-day Microsoft Purview solutions trial to explore how additional Purview capabilities can help your organization manage data security and compliance needs. Start now at the Microsoft Purview compliance portal trials hub. Learn details about signing up and trial terms.

Retention cmdlets for most locations

Use the cmdlets in the following table when the locations are Exchange mailboxes, SharePoint sites or SharePoint classic and communication sites, OneDrive accounts, Microsoft 365 Group mailboxes & sites, Skype for Business, Exchange public folders, Teams chat messages, or Teams channel messages.

Don't use these cmdlets when the locations are for Teams private channel messages, Viva Engage user messages, or Viva Engage community messages. These locations have alternative cmdlets that are identified in the [next section](#retention-cmdlets-specific-to-teams-private-channels-and-Viva Engage).

Cmdlet Description Applicable locations
Enable-ComplianceTagStorage

Get-ComplianceTagStorage
A one-time operation to create storage, or view that storage for retention labels Exchange mailboxes

SharePoint sites (or SharePoint classic and communication sites)

OneDrive accounts

Microsoft 365 Group mailboxes & sites
Get-ComplianceTag

New-ComplianceTag

Remove-ComplianceTag

Set-ComplianceTag
View, create, delete, configure retention labels Exchange mailboxes

SharePoint sites (or SharePoint classic and communication sites)

OneDrive accounts

Microsoft 365 Group mailboxes & sites
Get-RecordReviewNotificationTemplateConfig

Set-RecordReviewNotificationTemplateConfig
View or configure the disposition review notification and reminder settings Exchange mailboxes

SharePoint sites (or SharePoint classic and communication sites)

OneDrive accounts

Microsoft 365 Group mailboxes & sites
Get-RetentionCompliancePolicy

New-RetentionCompliancePolicy

Remove-RetentionCompliancePolicy

Set-RetentionCompliancePolicy
View, create, delete, configure retention policies and retention label policies Exchange email

SharePoint sites (or SharePoint classic and communication sites)

OneDrive accounts

Microsoft 365 Group mailboxes & sites

Skype for Business

Exchange public folders

Teams chat messages

Teams channel messages
Get-RetentionComplianceRule

New-RetentionComplianceRule

Set-RetentionComplianceRule

Remove-RetentionComplianceRule
View, create, configure, delete settings (rules) for retention policies and retention labels Exchange email

SharePoint sites (or SharePoint classic and communication sites)

OneDrive accounts

Microsoft 365 Group mailboxes & sites

Skype for Business

Exchange public folders

Teams chat messages

Teams channel messages

Retention cmdlets specific to Teams private channels and Viva Engage

Use the following cmdlets when the locations are for Teams private channel messages, Viva Engage user messages, or Viva Engage community messages.

When the locations are for Teams chat messages, Teams channel messages, Exchange email, SharePoint sites (or SharePoint classic and communication sites), OneDrive accounts, Microsoft 365 Group mailboxes & sites, Skype for Business, or Exchange public folders, use the cmdlets listed in the previous section.

Cmdlet Description Applicable locations
Get-AppRetentionCompliancePolicy

New-AppRetentionCompliancePolicy

Remove-AppRetentionCompliancePolicy

Set-AppRetentionCompliancePolicy
View, create, delete, configure retention policies Teams private channel messages

Viva Engage user messages

Viva Engage community messages
Get-AppRetentionComplianceRule

New-AppRetentionComplianceRule

Remove-AppRetentionComplianceRule

Set-AppRetentionComplianceRule
View, create, configure, delete settings (rules) for retention policies Teams private channel messages

Viva Engage user messages

Viva Engage community messages

Configuration guidance

Use the help pages associated with each cmdlet for detailed information and examples.

For guided help to create and then publish retention labels, see Create and publish retention labels by using PowerShell.