Hi, i'm Lucian and here I share my experiences, thoughts and opinions on life in the blue cloud. I'm a Cloud Solution Architect, specialising in Azure infrastructure, at Microsoft, in Sydney, Australia.

How to add users to an Exchange Online in-place hold

How to guide with sample PowerShell script(s).

A month ago I wrote a quick post (available here) on removing users from large in-place hold polices in Exchange Online. At the time I wasn’t that familiar with the process and documentation online was limited. After sharing is caring that process I had a deeper look into the in-place hold policies for a client I’m consultant at. There was some clean-up that was required and this post explains that process as well as a streamlined way via PowerShell to add users to an in-place hold policy.

The problem

Over the course of any large-scale migration to Exchange Online, managed services and project resource teams coordinate to successfully migrate users and apply policies and post migration tasks. In-place hold policies and governance around storing email data for compliance and legal purposes is key for certain organisations. The larger the organisation though, the more tricky the task. The GUI or web console just isn’t enough to cater for thousands of users. Insert PowerShell!- it is your friend.

The solution

Overall the process to add users to an in-place hold isn’t that much different from the process of removing users from a policy. Like the previous post, I’ll keep the process short and sweet to outline the steps required:

Get the data

Run the following PowerShell to create a variable in your PS session grabbing all the mailboxes in the hold policy called “Lucians Mailbox Search Policy”:

# Create a variable which will get the mailbox search
$check = Get-MailboxSearch “Lucian’s Mailbox Search Policy"

Review the data

It’s always good to see what mailboxes are covered under the in-place hold. To check those mailboxes enter the following cmdlet:

# To view any mailboxes that are currently in the policy

Back this up!

I’ve included this as an additional step to be safe in that if you delete too many users, you can go back and restore the original policy.

# To list all the mailboxes in the hold, as well as back up the data, run the following
# This will save the sources.txt file in your current PowerShell target, eg: PS C:\TEMP>
$check.sources > sources.txt

Adding users

This step follows the same lines as removing users, only, we change the syntax to specify the command “add” rather than “remove”:

# Add mailboxes to the mailbox search list

Important note!

To add users to the in-place hold policy successfully, the formatting needs to be correct. It’s natural to assume that using a mailbox UPN or PrimarySMTPAddress is fine. Certainly a unique attribute like UPN should work. However, the process requires the use of attribute DistinguishedName. In hybrid environments that is not the DN of the on-premises synchronised user object, but rather, the DN in Azure AD/Office 365 which is a different DN from the on-premises DN. It’s easy to grab that from a mailbox by entering the following:

Get-Mailbox -Identity "Lucian" | select DistinguishedName

Adding mailboxes via their DN is easy enough. However, sometimes invalid characters can come up in CSV’s or spreadsheets. When this happens, say there are 2,500 mailboxes being added via this process, and all looks great until the final step (below), PowerShell will error and say something alone the lines of:

The operation couldn’t be performed because object [email protected] couldn’t be found on SIXPR0000000000.APCPR000000.prod.outlook.com.

Save and go live

The final step is to save the new list of SourceMailboxes to the live in-place hold policy.

# Sets your prod/live in-place hold to be the current PS sessions hold, minus the 3 users removed
Set-MailboxSearch "Lucian’s Mailbox Search Policy" -SourceMailboxes $check.sources

Once this has completed successfully, the following line will be displayed in PowerShell:

WARNING: The hold setting may take up to 60 minutes to take effect.


In-place hold polices have numerous limitations applying to various links in the chain, including the policy items, mailboxes and even Exchange admin. There’s a Microsoft TechNet article (available here) outlining these limits. What isn’t very black and white though is how many policies can be applied to a mailbox. As in: can a mailbox have multiple policies applied to it. Short answer: YES, multiple policies can apply to a mailbox.

Having multiple policies applied to a mailbox comes in handy for one main reason. Administration! To paint a word picture; mailbox policies can sometimes be kept out of check. System administrators can apply incorrect policies or even provision new policies for individual mailboxes, rather than a uniform set of policies governing many users.

To explain why having multiple policies applied to mailboxes is a good thing in relation to administration: is so a mailbox can be moved between policies without losing held data. A new policy is applied to a mailbox; a waiting period is set to allow EXO to replicate the data that is in the old policy to the new; and finally the old policy can be removed from the mailbox and potentially removed from EXO altogether.

Final words

Running through tens of thousands of mailboxes and quickly moving between policies significantly reduces administrative time. One of the many reasons why powershell is your friend!