[Update]: This blog post was updated on March 7, 2022.
AAs announced in this Microsoft articlemoved the retirement date for legacy eDiscovery tools from April 1, 2020 to July 1, 2020. At this point, the Search-Mailbox cmdlet lost its official support. Many admins (including me) thought this meant Search-Mailbox stopped working. As it turns out, in early 2022, Search-Mailbox still works like a charm (assuming you have the right permissions). There’s no telling if it will eventually break or not, so in this article I’m going to demonstrate how to use the New-ComplianceSearch cmdlet instead of its long-lived predecessor, Search-Mailbox.
End of life of the search mailbox
For a while now, the Search-Mailbox cmdlet has been returning a warning that it will be deprecated soon. The exact time of end of life is set for July 1, 2020 (postponed from April 1, 2020). Note that if you’re still using Exchange 2010,
For a while now, the Search-Mailbox cmdlet has been returning a warning that it will be deprecated soon. According to the warning returned by PowerShell, the end of life was set to July 1, 2020 (previously April 1, 2020). Although not officially supported, it still works in 2022. So if you need to remove mailbox items in bulk, read this article to learn how to use Search-Mailbox to do it. It might be worth using this method before shutting down for good.
While Search-Mailbox seems to be working fine for now, it still returns a warning that the cmdlet is being retired. Because of this, learning to use the recommended Alternative ComplianceSearch cmdlets is still a must. Let’s see what the differences are between the old and the new method of searching mailboxes.
Comparison between ComplianceSearch and Search-Mailbox
The Search-Mailbox cmdlet could be used to:
- recover deleted items (invisible from user perspective),
- copy specific items to a discovery mailbox,
- delete or delete mailbox contents,
- Estimation results for a selected query.
These capabilities along with the highly customizable -SearchQuery attribute made this single cmdlet extremely useful. Don’t get me wrong, using this cmdlet wasn’t everything:
- They had to work around the 10,000 result limit.
- KQL used in the search query might be a bit cumbersome, especially when you include multiple conditions. But to be honest, the -ContentMatchQuery attribute in the new search experience also uses KQL.
- There was no way to recover deleted items in the same mailbox – the target mailbox had to be different from the searched mailbox.
Now you can achieve similar results with the *-ComplianceSearch cmdlet family, but the way you do this is a bit like switching from message tracking logs to Office 365 Message Trace. The basic differences are:
- Search Mailbox requires the mailbox search Role to perform searches or the Mailbox Import Export Role to delete items. *-ComplianceSearch Cmdlets require one of these roles AND a security and compliance role.
- With Search-Mailbox, you could use a single cmdlet to search and delete some mailbox content, while ComplianceSearch requires a few steps.
- Search-Mailbox (as the name suggests) only processed mailbox-related content. ComplianceSearch is based on Unified Search and can therefore also be run from SharePoint sites and public folders.
- For ComplianceSearch cmdlets, launching a remote PowerShell session with Exchange Online is not sufficient. You also need to connect to the Security & Compliance module.
- Any New-ComplianceSearch you perform can be viewed in Office 365 Compliance Center.
- New-ComplianceSearchAction is not intended for a bulk purge of mailboxes as it only deletes 10 articles per mailbox at the same time.
Prepare to use Compliance Search
Two prerequisites that are required before taking any action related to compliance search are connection to the correct Office 365 services. You can do this in a single PowerShell session using the following cmdlets:
Connect-ExchangeOnline Connect-IPPSSession -UserPrincipalName <your UPN>
You will be prompted to enter your Office 365 admin credentials. After that, the console tries to establish remote connections to Exchange Online and Security & Compliance PowerShell. The correct modules are automatically installed and imported along with the accessible cmdlets.
Read about prerequisites and troubleshooting for the modern method of connecting to Exchange Online
Next you need to make sure you have the right permissions. Run the following cmdlet to find out who has access to the Mailbox Search role:
Get-ManagementRoleAssignment -Role "Mailbox Search" -GetEffectiveUsers -Delegating $false
The easiest way to assign this role is to add yourself to a group that contains this role, for example:
Add-RoleGroupMember "Discovery Management" -member [email protected]
Note that the mailbox search Role allows creating searches, but only those Mailbox Import Export Role gives administrators the right to delete or export the search results.
The next step is to verify the eDiscovery admins:
Get-eDiscoveryCaseAdmin
And add yourself to this group if you like:
Add-eDiscoveryCaseAdmin [email protected]
How do I run a ComplianceSearch cmdlet?
Once you are connected and given the correct permissions, you can start a search. First you need to configure a search using the New-ComplianceSearch cmdlet. For example, you can search all mailboxes and search for a specific keyword in the message subject:
New-ComplianceSearch -name "suspicious emails" -ExchangeLocation all -ContentMatchQuery 'subject:"suspicious"'
Or base your search on a date items were received. For example, this short script below returns articles two days old and newer:
$date= (get-date).adddays(-2); $date = $date.ToShortDateString(); $date = [scriptblock]::create($date); New-ComplianceSearch "mailbox items newer than 2 days" -ExchangeLocation all -ContentMatchQuery "received>=$date"
The -ContentMatchQuery attribute works the same as the -SearchQuery attribute in Search-Mailbox. Check out a detailed guide on how to use the search query.
If you want to search inactive mailboxes, you need an additional attribute: -AllowNotFoundExchangeLocationsEnabled $true. Also, if you’re targeting your search at a single inactive mailbox, its UPN must be prefixed with a period (.), like this:
New-ComplianceSearch "Search inactive mailbox" -ExchangeLocation [email protected] -AllowNotFoundExchangeLocationsEnabled $true
After setting up conditions for searching, you need to run a separate cmdlet to start them:
Start-ComplianceSearch “suspicious emails”
You can also pipe the New-ComplianceSearch cmdlet to Start-ComplianceSearch as follows:
New-ComplianceSearch … | Start-ComplianceSearch
Run the following cmdlet to check the progress of your search and get basic information about the current results:
Get-ComplianceSearch | FL name,items,size,jobprogress,status
What happens when you rerun a compliance search?
You can restart a search that has already been completed. That’s good news – it means you can repeat searches with the most common searches. Or use the Set-ComplianceSearch Cmdlet to change search criteria and Start-ComplianceSearch directly after.
How to delete mailbox content in Office 365 using PowerShell
After you have set up and completed the ComplianceSearch, you must use New-ComplianceSearchAction
with the -Clean Attribute for deleting elements, for example:
New-ComplianceSearchAction -SearchName “suspicious emails” -purge -purgetype SoftDelete/HardDelete
If you don’t specify them -PurgeType attribute, the results are soft-deleted, which means users can recover those deleted items until the retention period has elapsed. That HardDelete value deletes items forever unless a litigation hold or retention policy is in place to prevent deletion of specific items. Note that the New-ComplianceSearchAction’s 10 items per mailbox limit requires that you perform precision searches or run the cmdlet in a loop.
Learn more about retention policies and litigation holds in Office 365
Troubleshooting
There are some common issues that you may encounter during this procedure. Below I list the most common mistakes and ways to counteract them.
Not recognized as a cmdlet name
One of the most common errors known to PowerShell users is:
New-ComplianceSearchAction: The term 'New-ComplianceSearchAction' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.
The problem is that there can be a few reasons for this warning to appear:
- problem: Failed to connect to the Security & Compliance Center
solution: Run Get-PSSession to verify your remote sessions exist Open and Available. You can useGet-PSSession | Remove-PSSessionand repeat the steps below Prepare to use Compliance Search. Make sure you’re using the correct credentials. - problem: Error importing module with available cmdlets
solution: For some reason, your PowerShell session may not have been able to import the correct Office 365 service module. Run it to fix itGet-Module | Import-Module - Problem: Missing permissions
solution: If you do not have permissions, you must have them assigned to you. If you don’t have sufficient permissions to assign yourself to a member of the correct role group, you must request access from another administrator. - problem: Connection timed out
solution: Your remote session may expire after a while. To fix the problem, repeat the steps below Prepare to use Compliance Search. - problem: Cmdlet misspelled
solution: I have seen New-ComplianceSearch more times than I’m willing to admit. I even thought about making one New-ComplianceSearch Alias for the correct cmdlet. I may be the only one typing the cmdlets manually, but it doesn’t hurt to check your spelling when typing a cmdlet.
The search is still ongoing
This error occurs when you are too hasty or when you run searches with very broad criteria.
Unable to execute the task. Reason: The search "*" is still running or it didn't return any results. Please wait until the search finishes or edit the query and run the search again.
To speed up the search, make sure you only search the relevant directories.
Run the following to check the status of compliance searches:
Get-ComplianceSearch | FL name,items,size,jobprogress,status
The compliance search object already exists
This error is caused by running New-ComplianceSearch with a name that already exists.
The compliance search object "*" already exists within your organization.
To resolve the issue, either use a new unique name or run Set-ComplianceSearch instead.
