AboutFree templates
How-to · Microsoft 365 admin

Place mailboxes and sites on hold before a migration

At the end, the mailboxes, SharePoint sites and OneDrive accounts in scope are covered by a retention policy or Litigation Hold, you have a list of every hold in place, and you know how to release them when the migration is finished.

Updated 11 steps8 official sources
Start hereBack to the playbook
Before you start

What you need before step 1

Applies to: Microsoft 365 with Exchange Online, SharePoint and OneDrive: Microsoft Purview retention policies and Exchange Online Litigation Hold, as documented by Microsoft

Admin roles you need

  • Retention policies: membership of the Compliance Administrator role group in Microsoft Purview, or a custom role group with the Retention Management role. View-Only Retention Management is read-only.
  • Litigation Hold: an Exchange Online role that can run Set-Mailbox with -LitigationHoldEnabled. Step 6 shows how to find which roles in your tenant have it.
  • Removing a delay hold early: the Legal Hold role in Exchange Online, as Microsoft states.

Licences

  • Litigation Hold: Microsoft says the mailbox needs an Exchange Online Plan 2 licence, or Exchange Online Plan 1 plus an Exchange Online Archiving licence.
  • Retention policies: check Microsoft's licensing guidance for Microsoft Purview data lifecycle management for your plan.

Web portals you will use (nothing to install)

Microsoft Purview portalWeb portal for retention policies; nothing to installhttps://purview.microsoft.comOpen
Microsoft 365 admin centerWeb portal; used to turn on Litigation Hold for one userhttps://admin.microsoft.comOpen

Reference documentation

Exchange Online PowerShell (ExchangeOnlineManagement module)Install instructions; see our how-to Connect to Exchange Online PowerShellhttps://learn.microsoft.com/powershell/exchange/exchange-online-powershell-v2Our step-by-step →Read

Also have ready

  • Written agreement from your legal, records or compliance owner on what must be kept, for how long, and whether any existing hold can be released for the migration.
  • The list of mailboxes, sites and OneDrive accounts that will move.
  • Time: Microsoft says a new retention policy can take up to seven days to apply, and the Microsoft 365 admin center warns Litigation Hold can take up to 240 minutes. Do this well before the first migration pass.
Step by step

11 steps

  1. 1

    Know why holds matter in a migration

    Where: Planning, before you touch any setting

    A hold makes sure that nothing users or migration clean-up delete is permanently lost while data is being copied. Microsoft's rule is that retention wins over deletion: deleted mail stays in Recoverable Items and deleted files stay in the site's Preservation Hold library.

    Holds can also block a move. For cross-tenant mailbox migration Microsoft says: mailboxes that are on any type of hold aren't migrated, and the move for those mailboxes is blocked. Held content in the Preservation Hold library also counts toward the site's storage quota. Decide per migration whether you are adding holds (to protect the source) or recording and releasing them (to allow a cross-tenant move), and get that decision in writing.

    You should see: A signed-off decision for each workload: add a hold, keep the existing hold, or release it for the move and reapply in the target.
  2. 2

    List the holds already in place

    Where: Exchange Online PowerShell on your admin PC (see Connect to Exchange Online PowerShell)

    Connect, then list every mailbox with Litigation Hold or another hold, and the organisation-wide holds. In InPlaceHolds, a GUID starting mbx is a Purview retention policy, grp is a policy for Microsoft 365 Groups and Teams channel messages, UniH is an eDiscovery hold, and no prefix or cld is an old In-Place Hold. Save the output to your migration records.

    Connect-ExchangeOnline -UserPrincipalName admin@contoso.com
Get-Mailbox -ResultSize Unlimited | Where-Object {$_.LitigationHoldEnabled -or $_.InPlaceHolds} | Format-Table Name,LitigationHoldEnabled,InPlaceHolds -Auto
Get-OrganizationConfig | Format-List InPlaceHolds
    You should see: A table of held mailboxes (empty if none) and the organisation-wide InPlaceHolds value.
  3. 3

    Open Retention policies in Microsoft Purview

    Where: Microsoft Purview portal (purview.microsoft.com) > Solutions > Data Lifecycle Management > Policies > Retention policies

    Sign in with an account in the Compliance Administrator role group and follow the menu path. Select New retention policy.

    You should see: The new retention policy wizard opens on the name page.
  4. 4

    Name the policy and pick its type

    Where: New retention policy wizard

    Enter a clear name such as Migration hold - Contoso 2026 and a description. You cannot rename it later. On Assign admin units keep Full directory. On Choose the type of retention policy to create select Static (Adaptive needs adaptive scopes to exist already). Select Next.

    You should see: The Choose locations to apply the policy page.
  5. 5

    Choose the locations to hold

    Where: New retention policy wizard > Choose locations to apply the policy

    Turn on the locations being migrated: Exchange mailboxes, SharePoint sites (shown as SharePoint classic and communication sites), OneDrive accounts, and Microsoft 365 Group mailboxes & sites for group and Teams-connected content. Each defaults to all users or sites; use the Choose and Exclude options to limit it to the users and sites in scope. Teams chats and channel messages need a separate policy, because selecting a Teams location excludes the others. Select Next.

    You should see: The Decide if you want to retain content, delete it, or both page.
  6. 6

    Set it to retain only

    Where: New retention policy wizard > Decide if you want to retain content, delete it, or both

    For a migration safety net, choose a policy that only keeps content: select Retain items for a specific period, enter a period that covers the project plus a margin, and for At end of the retention period select Do nothing. Or select Retain items forever if compliance asks for it. Do not choose any delete option. Select Next, review, and submit.

    You should see: A confirmation that the policy was created. Back on Retention policies, the policy is listed.
  7. 7

    Find who can set Litigation Hold

    Where: Exchange Online PowerShell on your admin PC

    Use Litigation Hold for individual mailboxes that legal needs held regardless of policy. First check which role assignments in your tenant can use the parameter.

    $Perms = Get-ManagementRole -Cmdlet Set-Mailbox -CmdletParameters LitigationHoldEnabled
$Perms | foreach {Get-ManagementRoleAssignment -Role $_.Name -Delegating $false | Format-Table -Auto Role,RoleAssigneeType,RoleAssigneeName}
    You should see: A table of roles and the role groups or users assigned them. Your account, or a group you belong to, should be listed.
  8. 8

    Turn on Litigation Hold for one user in the portal

    Where: Microsoft 365 admin center (admin.microsoft.com) > Users > Active users > select the user > Mail tab

    Under More actions select Manage litigation hold. Tick Turn on litigation hold. Leave Hold duration (days) blank to hold indefinitely, or enter days. Optionally fill Note visible to the user and Web page with more information for the user. Select Save changes. If Manage litigation hold is missing, the mailbox probably lacks an Exchange Online Plan 2 licence.

    You should see: A banner saying it might take up to 240 minutes for the change to take effect.
  9. 9

    Or turn on Litigation Hold with PowerShell

    Where: Exchange Online PowerShell on your admin PC

    Place one mailbox on hold indefinitely, one for a set number of days (counted from when each item was received or created), or every user mailbox. The bulk command only covers mailboxes that exist when you run it, so run it again after creating new mailboxes. -RetentionComment and -RetentionUrl set the note and link shown in Outlook.

    Set-Mailbox -Identity chris@contoso.com -LitigationHoldEnabled $true
Set-Mailbox -Identity chris@contoso.com -LitigationHoldEnabled $true -LitigationHoldDuration 365
Get-Mailbox -ResultSize Unlimited -Filter "RecipientTypeDetails -eq 'UserMailbox'" | Set-Mailbox -LitigationHoldEnabled $true
Set-Mailbox -Identity chris@contoso.com -RetentionComment "Your mailbox is on hold during the migration" -RetentionUrl "https://intranet.contoso.com/migration"
    You should see: The prompt returns with no error. A hold with no duration shows LitigationHoldDuration Unlimited.
  10. 10

    Check the policy has been distributed

    Where: Microsoft Purview portal > Data Lifecycle Management > Policies > Retention policies > select your policy

    Open the policy to see its distribution status in the flyout. If it shows (Error), retry distribution from Security & Compliance PowerShell (Connect-IPPSSession, which Microsoft notes is not available in PowerShell 7 on macOS).

    Connect-IPPSSession -UserPrincipalName admin@contoso.com
Set-RetentionCompliancePolicy -Identity "Migration hold - Contoso 2026" -RetryDistribution
    You should see: The flyout shows a successful distribution status with no (Error). Allow up to seven days before relying on it.
  11. 11

    Release holds after the migration

    Where: Microsoft Purview portal and Exchange Online PowerShell, only after compliance signs off

    Delete the retention policy, or open it and turn the locations off or disable it. Remove Litigation Hold with Set-Mailbox. Microsoft applies a 30-day delay hold to a mailbox after any hold is removed, and keeps SharePoint and OneDrive content for a 30-day grace period after a policy is released. Only remove a delay hold early if you are sure, and only with the Legal Hold role.

    Set-Mailbox -Identity chris@contoso.com -LitigationHoldEnabled $false
Get-Mailbox -Identity chris@contoso.com | Format-List *HoldApplied*
Set-Mailbox -Identity chris@contoso.com -RemoveDelayHoldApplied
    You should see: LitigationHoldEnabled is False, and DelayHoldApplied is True until the 30 days pass or you remove it.
From experience

Expert tips

Start a week before the first pass

Microsoft says a new retention policy can take up to seven days to apply, and Litigation Hold up to 240 minutes. A policy created the day before cutover may not protect anything yet. Create it early and confirm distribution status before relying on it.

For cross-tenant moves, release holds deliberately

Microsoft says mailboxes on any type of hold are not migrated cross-tenant, and the move is blocked. Export the hold inventory from step 2, get written sign-off, release the holds, and check Get-Mailbox <user> | Format-List *HoldApplied*: a 30-day delay hold applies after removal, and only someone with the Legal Hold role can remove it early. Reapply retention in the target as soon as data lands.

Retain only, and never add Preservation Lock

Use Retain items for a specific period with Do nothing at the end, or retain forever if compliance asks. Never add Preservation Lock to a temporary migration policy: Microsoft says no one, including an administrator, can then turn it off, delete it or make it less restrictive.

Budget SharePoint storage for held content

Under a hold, deleted and changed files are kept in the site's Preservation Hold library, which counts toward the site's storage quota. Migration clean-up, reruns and restructures can grow it quickly. Watch storage on large sites and exclude sites that are not in scope.

Rerun bulk Litigation Hold after creating mailboxes

The bulk Set-Mailbox -LitigationHoldEnabled $true command only covers mailboxes that exist when you run it. Rerun it after each migration wave creates new mailboxes, or use a retention policy scoped to all mailboxes instead.

Check holds before deleting source mailboxes

A mailbox with DelayHoldApplied or DelayReleaseHoldApplied set to True is treated as on hold, so deleting it after migration creates an inactive mailbox rather than freeing it. Check the hold properties before decommissioning, and decide with compliance whether an inactive mailbox is what you want.

Check it worked

How to confirm it worked

  • Get-Mailbox chris@contoso.com | Format-List LitigationHold* shows LitigationHoldEnabled True.

  • Get-Mailbox chris@contoso.com | Format-List InPlaceHolds lists a GUID starting mbx once a mailbox retention policy has applied (an organisation-wide policy shows in Get-OrganizationConfig instead).

  • In the Microsoft Purview portal, Retention policies shows your policy with a successful distribution status.

Undo

How to reverse it

Rollback:

Delete or disable the retention policy in the Microsoft Purview portal, and run Set-Mailbox <user> -LitigationHoldEnabled $false. Expect the 30-day delay hold on mailboxes and the 30-day grace period on SharePoint and OneDrive. Warning: if anyone adds Preservation Lock to a policy, Microsoft says no one, including an administrator, can turn it off, delete it or make it less restrictive. Never add Preservation Lock to a temporary migration policy.

Troubleshooting

Errors you might see

Manage litigation hold option missing in the Microsoft 365 admin center

Cause: Microsoft says this can mean the mailbox is not assigned an Exchange Online Plan 2 licence.

Fix: Assign Exchange Online Plan 2, or Exchange Online Archiving alongside Plan 1, then try again.

Retention policy status shows (Error), with "taking longer than expected to deploy the policy" or "try redeploying the policy"

Cause: Distribution to one or more locations failed.

Fix: In Security & Compliance PowerShell run Set-RetentionCompliancePolicy -Identity -RetryDistribution.

Mailboxes that are on any type of hold aren't migrated, and the move for those mailboxes is blocked.

Cause: Cross-tenant mailbox migration does not move held mailboxes.

Fix: With compliance approval, record and release the hold (and wait out or remove the delay hold), migrate, then reapply retention in the target tenant.

Mailbox deleted after migration becomes an inactive mailbox

Cause: Microsoft says a mailbox with DelayHoldApplied or DelayReleaseHoldApplied True is treated as on hold, so deleting it creates an inactive mailbox.

Fix: Check Get-Mailbox | Format-List *HoldApplied* before you delete source mailboxes.

FAQ

Questions

Should I use a retention policy or Litigation Hold?

A retention policy covers many locations at once, including SharePoint and OneDrive. Litigation Hold is per mailbox and is the quick option for specific people. Many projects use a retain-only policy for the estate and Litigation Hold for named custodians.

Does a hold slow down or stop a migration within one tenant?

A hold keeps copies of deleted and changed items; it does not stop users working. For cross-tenant mailbox moves Microsoft says held mailboxes are blocked, so plan releases.

Does a hold move with the mailbox to another tenant?

No. Holds and retention policies are tenant settings. Recreate them in the target and apply them as soon as data lands.

Will users notice?

Usually not. Held copies are kept in Recoverable Items and the Preservation Hold library, which most people cannot see. Users only see a note if you set one.

Sources

Official sources

Vendors change menus and requirements. Confirm on the source before you rely on a detail. Last checked 4 Nov 2026.

Microsoft Learn: Create and configure retention policiesMicrosoft Learn: Common settings for retention policies and retention labelsMicrosoft Learn: Learn about retention policies and retention labelsMicrosoft Learn: Get started with data lifecycle managementMicrosoft Learn: Place a mailbox on litigation hold (Microsoft 365 admin center)Microsoft Learn: How to identify the type of hold placed on an Exchange Online mailboxMicrosoft Learn: Set-MailboxMicrosoft Learn: Cross-tenant mailbox migration