PowerShell cmdlets for retention policies and retention labels
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.
| 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.