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 Center 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. The policy then requires one rule to complete the configuration.

For example:

  • A retention policy needs 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, you can try all the premium features in Microsoft Purview for free. Use the 90-day Purview solutions trial to explore how robust 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 email, SharePoint sites, OneDrive accounts, Microsoft 365 Groups, 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, Yammer user messages, or Yammer community messages. These locations have alternative cmdlets that are identified in the next section.

Cmdlet Description Applicable locations
Enable-ComplianceTagStorage

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

SharePoint sites

OneDrive accounts

Microsoft 365 Groups
Get-ComplianceTag

New-ComplianceTag

Remove-ComplianceTag

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

SharePoint sites

OneDrive accounts

Microsoft 365 Groups
Get-RecordReviewNotificationTemplateConfig

Set-RecordReviewNotificationTemplateConfig
View or configure the configuration for disposition review notification and reminder settings Exchange email

SharePoint sites

OneDrive accounts

Microsoft 365 Groups
Get-RetentionCompliancePolicy

New-RetentionCompliancePolicy

Remove-RetentionCompliancePolicy

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

SharePoint sites

OneDrive accounts

Microsoft 365 Groups

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 for polices for retention or retention labels Exchange email

SharePoint sites

OneDrive accounts

Microsoft 365 Groups

Skype for Business

Exchange public folders

Teams chat messages

Teams channel messages

Retention cmdlets specific to Teams private channels and Yammer

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

When the locations are for Teams chat messages, Teams channel messages, Exchange email, SharePoint sites, OneDrive accounts, Microsoft 365 Groups, 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

Yammer user messages

Yammer community messages
Get-AppRetentionComplianceRule

New-AppRetentionComplianceRule

Remove-AppRetentionComplianceRule

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

Yammer user messages

Yammer 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.