Share via

Apply a retention policy to mailboxes in Exchange Online

  • Article

Note

To proactively retain or delete mailbox content for data lifecycle management in Microsoft 365, we recommend that you use retention policies and retention labels from the Microsoft Purview 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 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 use retention policies to group one or more retention tags and apply them to mailboxes to enforce message retention settings. A mailbox can't have more than one retention policy.

Caution

Messages are expired based on settings defined in the retention tags linked to the policy. These settings include actions such moving messages to the archive or permanently deleting them. Before applying a retention policy to one or more mailboxes, we recommended that you test the policy and inspect each retention tag associated with it.

For additional management tasks related to messaging records management (MRM), see Messaging Records Management Procedures.

What do you need to know before you begin?

  • Estimated time to complete: 5 minutes.

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

Tip

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

Use the new EAC to apply a retention policy to a single mailbox

  1. Sign in to the new Exchange admin center and navigate to Recipients > Mailboxes.

  2. In the list view, select the mailbox to which you want to apply the retention policy.

  3. In the details panes for that mailbox, select Mailbox, and then for the Retention policy section, select Manage mailbox policies.

  4. In the Mailbox policies pane, use the dropdown list box for Retention policy to select the policy you want to apply to the mailbox, and then select Save.

Use the new EAC to apply a retention policy to multiple mailboxes

  1. Sign in to the new Exchange admin center and navigate to Recipients > Mailboxes.

  2. In the list view, select the multiple mailboxes to apply the same retention policy.

  3. Above the list view, select ... for more options, and select Mailbox policies.

  4. In the Mailbox policies pane, use the dropdown list box for Retention policy to select the policy you want to apply to the multiple mailboxes, and then select Save.

Use Exchange Online PowerShell to apply a retention policy to a single mailbox

The following example applies the retention policy RP-Finance to Morris's mailbox:

PowerShell 
Set-Mailbox "Morris" -RetentionPolicy "RP-Finance"

For detailed syntax and parameter information, see Set-Mailbox.

Use Exchange Online PowerShell to apply a retention policy to multiple mailboxes

The following example applies the new retention policy New-Retention-Policy to all mailboxes that have the old policy Old-Retention-Policy:

PowerShell 
$OldPolicy=(Get-RetentionPolicy "Old-Retention-Policy").distinguishedName
Get-Mailbox -Filter "RetentionPolicy -eq '$OldPolicy'" -Resultsize Unlimited | Set-Mailbox -RetentionPolicy "New-Retention-Policy"

The following example applies the retention policy RetentionPolicy-Corp to all mailboxes in the Exchange organization:

PowerShell 
Get-Mailbox -ResultSize unlimited | Set-Mailbox -RetentionPolicy "RetentionPolicy-Corp"

The following example applies the retention policy RetentionPolicy-Finance to all mailboxes in the Finance organizational unit:

PowerShell 
Get-Mailbox -OrganizationalUnit "Finance" -ResultSize Unlimited | Set-Mailbox -RetentionPolicy "RetentionPolicy-Finance"

For detailed syntax and parameter information, see Get-Mailbox and Set-Mailbox.

How do you know this worked?

To verify that you have applied the retention policy, run the Get-Mailbox cmdlet to retrieve the retention policy for the mailbox or mailboxes.

The following example retrieves the retention policy for Morris's mailbox:

PowerShell 
Get-Mailbox Morris | Select RetentionPolicy

The following command retrieves all mailboxes that have the retention policy RP-Finance applied:

PowerShell 
Get-Mailbox -ResultSize unlimited | Where-Object {$_.RetentionPolicy -eq "RP-Finance"} | Format-Table Name,RetentionPolicy -Auto