Commands › Exchange Online

New-RetentionCompliancePolicy

Exchange Online ExchangeOnlineManagement New-*

For more information, see Security & Compliance PowerShell. Use the New-RetentionCompliancePolicy cmdlet to create new retention policies and new retention label policies in the Microsoft Purview compliance portal. Creating a new policy also requires use of the New-RetentionComplianceRule cmdlet.

Quick start script

# New-RetentionCompliancePolicy — quick start (serv365.ai)
# 1. Connect (app-only shown; interactive: omit the certificate parameters)
Connect-ExchangeOnline -CertificateThumbprint $thumb -AppId $appId -Organization $org

# 2. Capture the current state first — you cannot roll back what you never recorded
$before = Get-RetentionCompliancePolicy
$before | Format-List

# 3. Make the change (dry run first)
New-RetentionCompliancePolicy -Name <String> -AdaptiveScopeLocation <MultiValuedProperty> -WhatIf
New-RetentionCompliancePolicy -Name <String> -AdaptiveScopeLocation <MultiValuedProperty>

# 4. Verify and diff
$after = Get-RetentionCompliancePolicy
Compare-Object ($before | Out-String) ($after | Out-String)

Syntax — 3 parameter sets

Default

New-RetentionCompliancePolicy [-Name] <String>
 [-Applications <MultiValuedProperty>]
 [-Comment <String>]
 [-Confirm]
 [-Enabled <Boolean>]
 [-ExchangeLocation <MultiValuedProperty>]
 [-ExchangeLocationException <MultiValuedProperty>]
 [-Force]
 [-IsSimulation]
 [-ModernGroupLocation <MultiValuedProperty>]
 [-ModernGroupLocationException <MultiValuedProperty>]
 [-OneDriveLocation <MultiValuedProperty>]
 [-OneDriveLocationException <MultiValuedProperty>]
 [-PolicyRBACScopes <MultiValuedProperty>]
 [-PolicyTemplateInfo <PswsHashtable>]
 [-PriorityCleanup]
 [-PublicFolderLocation <MultiValuedProperty>]
 [-RestrictiveRetention <Boolean>]
 [-RetainCloudAttachment <Boolean>]
 [-SharePointLocation <MultiValuedProperty>]
 [-SharePointLocationException <MultiValuedProperty>]
 [-SkipPriorityCleanupConfirmation]
 [-SkypeLocation <MultiValuedProperty>]
 [-SkypeLocationException <MultiValuedProperty>]
 [-WhatIf]
 [<CommonParameters>]

TeamLocation

New-RetentionCompliancePolicy [-Name] <String>
 [-Comment <String>]
 [-Confirm]
 [-Enabled <Boolean>]
 [-Force]
 [-IsSimulation]
 [-PriorityCleanup]
 [-RestrictiveRetention <Boolean>]
 [-RetainCloudAttachment <Boolean>]
 [-SkipPriorityCleanupConfirmation]
 [-TeamsChannelLocation <MultiValuedProperty>]
 [-TeamsChannelLocationException <MultiValuedProperty>]
 [-TeamsChatLocation <MultiValuedProperty>]
 [-TeamsChatLocationException <MultiValuedProperty>]
 [-WhatIf]
 [<CommonParameters>]

AdaptiveScopeLocation

New-RetentionCompliancePolicy [-Name] <String> -AdaptiveScopeLocation <MultiValuedProperty>
 [-Applications <MultiValuedProperty>]
 [-Comment <String>]
 [-Confirm]
 [-Enabled <Boolean>]
 [-Force]
 [-IsSimulation]
 [-PriorityCleanup]
 [-RestrictiveRetention <Boolean>]
 [-RetainCloudAttachment <Boolean>]
 [-SkipPriorityCleanupConfirmation]
 [-WhatIf]
 [<CommonParameters>]

Parameters (30)

Parameter	Type	Required	What it controls
-Name	String	yes	The Name parameter specifies the unique name of the retention policy. If the value contains spaces, enclose the value in quotation marks.
-AdaptiveScopeLocation	MultiValuedProperty	yes	The AdaptiveScopeLocation parameter specifies the adaptive scope location to include in the policy. You create adaptive scopes by using the New-AdaptiveScope cmdlet. You can use any value that uniquely identifies the...
-Applications	MultiValuedProperty		The Applications parameter specifies the target when Microsoft 365 Groups are included in the policy (the ModernGroups parameter is set). Valid values are:
-Comment	String		The Comment parameter specifies an optional comment. If you specify a value that contains spaces, enclose the value in quotation marks ("), for example: "This is an admin note".
-Confirm	SwitchParameter		The Confirm switch specifies whether to show or hide the confirmation prompt. How this switch affects the cmdlet depends on whether the cmdlet requires confirmation before proceeding.
-Enabled	Boolean		The Enabled parameter specifies whether the policy is enabled or disabled. Valid values are:
-ExchangeLocation	MultiValuedProperty		The ExchangeLocation parameter specifies the mailboxes to include in the policy. Valid values are:
-ExchangeLocationException	MultiValuedProperty		The ExchangeLocationException parameter specifies the mailboxes to exclude from the policy when you use the value All for the ExchangeLocation parameter. Valid values are:
-Force	SwitchParameter		The Force switch hides warning or confirmation messages. You don't need to specify a value with this switch.
-IsSimulation	SwitchParameter		The IsSimulation switch specifies the policy is created in simulation mode. You don't need to specify a value with this switch.
-ModernGroupLocation	MultiValuedProperty		The ModernGroupLocation parameter specifies the Microsoft 365 Groups to include in the policy. Valid values are:
-ModernGroupLocationException	MultiValuedProperty		The ModernGroupLocationException parameter specifies the Microsoft 365 Groups to exclude from the policy when you use the value All for the ModernGroupLocation parameter.
-OneDriveLocation	MultiValuedProperty		The OneDriveLocation parameter specifies the OneDrive sites to include. You identify the site by its URL value, or you can use the value All to include all sites.
-OneDriveLocationException	MultiValuedProperty		This parameter specifies the OneDrive sites to exclude when you use the value All for the OneDriveLocation parameter. You identify the site by its URL value.
-PolicyRBACScopes	MultiValuedProperty		Note: Admin units aren't currently supported, so this parameter isn't functional. The information presented here is for informational purposes when support for admin units is released.
-PolicyTemplateInfo	PswsHashtable		This parameter is reserved for internal Microsoft use.
-PriorityCleanup	SwitchParameter		The PriorityCleanup switch specifies whether to create a Priority cleanup policy. You don't need to specify a value with this switch.
-PublicFolderLocation	MultiValuedProperty		The PublicFolderLocation parameter specifies that you want to include all public folders in the retention policy. You use the value All for this parameter.
-RestrictiveRetention	Boolean		The RestrictiveRetention parameter specifies whether Preservation Lock is enabled for the policy. Valid values are:
-RetainCloudAttachment	Boolean		Note: This parameter is currently in Preview, is not available in all organizations, and is subject to change.
-SharePointLocation	MultiValuedProperty		The SharePointLocation parameter specifies the SharePoint sites to include. You identify the site by its URL value, or you can use the value All to include all sites.
-SharePointLocationException	MultiValuedProperty		This parameter specifies the SharePoint sites to exclude when you use the value All for the SharePointLocation parameter. You identify the site by its URL value.
-SkipPriorityCleanupConfirmation	SwitchParameter		{{ Fill SkipPriorityCleanupConfirmation Description }}
-SkypeLocation	MultiValuedProperty		The SkypeLocation parameter specifies the Skype for Business Online users to include in the policy.
-SkypeLocationException	MultiValuedProperty		This parameter is reserved for internal Microsoft use.
-TeamsChannelLocation	MultiValuedProperty		The TeamsChannelLocation parameter specifies the Teams to include in the policy.
-TeamsChannelLocationException	MultiValuedProperty		The TeamsChannelLocationException parameter specifies the Teams to exclude when you use the value All for the TeamsChannelLocation parameter. You can use any value that uniquely identifies the team. For example:
-TeamsChatLocation	MultiValuedProperty		The TeamsChatLocation parameter specifies the Teams users to include in the policy.
-TeamsChatLocationException	MultiValuedProperty		The TeamsChatLocationException parameter specifies the Teams users to exclude when you use the value All for the TeamsChatLocation parameter. You can use any value that uniquely identifies the user. For example:
-WhatIf	SwitchParameter		The WhatIf switch doesn't work in Security & Compliance PowerShell.

Reference facts derived from Microsoft documentation, © Microsoft, licensed CC BY 4.0; restructured with original guidance by serv365.ai.