[Update]: This blog post was last updated on April 22, 2024. Search-Mailbox seems to be gone for good and the new method’s limit is upgraded from 10 to 100 items.
As announced in this Microsoft article, the date for retirement of legacy eDiscovery tools was moved from April 1, 2020 to July 1, 2020. That is when Search-Mailbox cmdlet lost its official support. While the Search-Mailbox did work for some time after this date, now you can use it only on on-premises Exchange. What about Exchange Online and Microsoft 365? Well, there’s a new sheriff in town and its name is New-ComplianceSearch. The cmdlet is a bit more troublesome to use, so I’ll do my best to show you how to come to terms with it.
Search-Mailbox end of life
For some time now, the Search-Mailbox cmdlet has been returning a warning that it will soon go out of use. According to the warning returned by PowerShell, its end of life was set to July 1, 2020 (previously April 1, 2020). Back in 2023, while not officially supported, it still worked. Right now, it’s not available in any tenant I check, after running Connect-ExchangeOnline and downloading all available cmdlets. Rest in peace, Search-Mailbox, we used you extensively.
So, right now, switching to ComplianceSearch cmdlets is no longer a choice – it’s a must. Let’s see what differences there are between the old and the new method of searching through mailboxes.
Comparison between ComplianceSearch and Search-Mailbox
The Search-Mailbox cmdlet could be used to:
- restore deleted items (invisible from the users’ perspective),
- copy certain elements to a discovery mailbox,
- delete or purge mailbox content,
- estimate results for a chosen query.
These capabilities, together with the highly customizable -SearchQuery attribute, made this single cmdlet extremely useful. Don’t get me wrong, using this cmdlet was not all roses:
- You
needed to work around the 10.000 results limit. - KQL
used in the SearchQuery could be a bit clunky, especially when you included
multiple conditions. But, to be honest, the -ContentMatchQuery attribute in the
new search experience uses KQL as well. - There
was no way to restore deleted elements to the same mailbox – the target mailbox
needed to be different from the searched mailbox.
Now, with the *-ComplianceSearch family of cmdlets, you can get similar results, but the way you do it is a bit like switching from the Message Tracking logs to Office 365 Message Trace. The basic differences are:
- Search-Mailbox required the Mailbox Search role to perform searches or the Mailbox Import Export role to delete items. *-ComplianceSearch cmdlets require one of those roles AND a security & compliance related 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) handled only mailbox-related content. ComplianceSearch is based on Unified Search, so it can also run through SharePoint sites and Public Folders.
- When it comes to ComplianceSearch cmdlets, starting a remote PowerShell session to Exchange Online will not suffice. You need to connect to the Security & Compliance module as well.
- Each New-ComplianceSearch you perform can be viewed in the Microsoft Purview compliance portal.
- New-ComplianceSearchAction is not intended for a mass cleanup of mailboxes, as it only deletes 100 items per mailbox at a time. If you think that the limit is ridiculous compared to the 10k in Search-Mailbox, then consider this: the New-ComplianceSearchAction limit was 10 items at first.
Prepare to use Compliance Search
Two prerequisites required before performing any Compliance Search-related actions is connecting to the right Office 365 services. You can do it in a single PowerShell session using the following cmdlets:
Connect-ExchangeOnline Connect-IPPSSession -UserPrincipalName <your UPN>
You will get prompted for your Office 365 administrator credentials. After that, the console will attempt to perform remote connections to Exchange Online and Security & Compliance PowerShell. The right modules, together with the accessible cmdlets, will be automatically installed and imported.
Next, you need to make sure you have the right permissions. Run the cmdlet below 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 which includes this role, for example:
Add-RoleGroupMember "Discovery Management" -member [email protected]
Mind that the Mailbox Search role allows to create searches, but only the Mailbox Import Export role gives admins the right to delete or export the search results.
The next step is to check eDiscovery Admins:
Get-eDiscoveryCaseAdmin
And add yourself to this group, if necessary:
Add-eDiscoveryCaseAdmin [email protected]
How to run a ComplianceSearch cmdlet?
As soon as you are connected and you have the right permissions assigned, you can start a search. First, you need to configure a search with the New-ComplianceSearch cmdlet. For example, you can search through all mailboxes, looking for a certain keyword in the message subject:
New-ComplianceSearch -name "suspicious emails" -ExchangeLocation all -ContentMatchQuery 'subject:"suspicious"'
In -ContentMatchQuery, you can use AND and OR logical operators if you need to work on the search scope some more. To base your search on a date the items were received, this short script below will, for example, return items 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"
And you can specify the date manually, as well. The safe format to use is YYYY-MM-DD
The -ContentMatchQuery attribute works the same as the -SearchQuery attribute in Search-Mailbox. See a detailed guide on how to use the SearchQuery.
If you want to search through inactive mailboxes, you need an additional attribute: -AllowNotFoundExchangeLocationsEnabled $true. Additionally, if you point your search to a single inactive mailbox, its UPN must be prepended with a period(.), like below:
New-ComplianceSearch "Search inactive mailbox" -ExchangeLocation [email protected] -AllowNotFoundExchangeLocationsEnabled $true
After you set up conditions for the search, you need to run a separate cmdlet to start it:
Start-ComplianceSearch "suspicious emails" /*or any other name that you specified. Run Get-ComplianceSearch to remind yourself what names you've used before.*/
You can also pipeline the New-ComplianceSearch cmdlet to Start-ComplianceSearch, like that:
New-ComplianceSearch … | Start-ComplianceSearch
To check the progress of your search and get some basic info about the current results, run the following cmdlet:
Get-ComplianceSearch | FL name,items,size,jobprogress,status
The funny thing you might experience right now is a set of surprising results:
Based on those results, I’d assume that all jobs were completed successfully, but no items were found. As you might suspect, the number of test searches you can see above stems from my attempt to find out what I did wrong.
As it turns out, it’s not me. Get-ComplianceSearch just isn’t completely honest. What’s surprising, when you run the cmdlet for a single Compliance Search case, it does return the correct values. So, to list all your Searches and actually learn something about them, run the following code:
$searches = Get-ComplianceSearch; foreach ($search in $searches){Get-ComplianceSearch $search.name | FL Name,Items,Size,JobProgress,Status}
What happens if you re-run a compliance search?
You can restart any search that has already been finished. That’s good news – it means you can rerun searches with the most common queries. Or use the Set-ComplianceSearch cmdlet to change search criteria and Start-ComplianceSearch immediately afterwards. Remember that SoftDeleted items will be returned in the results again.
How to delete mailbox contents in Office 365 using PowerShell
After you’ve set up and finished the ComplianceSearch, you need to use New-ComplianceSearchAction with the -Purge attribute to delete items, for example:
New-ComplianceSearchAction -SearchName "suspicious emails" -purge -purgetype /*SoftDelete / HardDelete*/
After you run the New-ComplianceSearchAction cmdlet, PowerShell will loyally inform you to think twice and confirm:
If you don’t specify the -PurgeType attribute, the results will be soft-deleted, meaning that users will be able to recover those deleted items before the retention period passes. The HardDelete value purges items for good, unless there is Litigation Hold or Retention Policy set up to prevent deleting certain items. Mind that the “10 items per mailbox” limit of the New-ComplianceSearchAction requires you to perform precision searches or looping the cmdlet.
Learn more about Retention Policies and Litigation Holds in Office 365
Troubleshooting
There are a few common problems you can run into during this procedure. Below, I list the most common errors and ways to counter them.
Not recognized as the name of a cmdlet
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 might be quite a few reasons for this warning to pop up:
- Problem: Failed to connect to the Microsoft Purview compliance portal
Solution: Run Get-PSSession to check if your remote sessions are Opened and Available. You can useGet-PSSession | Remove-PSSessionand repeat the steps from Prepare to use Compliance Search. Make sure to make to use the right credentials. - Problem: Failed to import module with available cmdlets
Solution: For some reason, your PowerShell session might have been unable to import the right Office 365 services module. To fix it, runGet-Module | Import-Module - Problem: Lack of permissions
Solution: If you lack permissions, you need to have them assigned to you. If you don’t have enough permissions to assign yourself a member of the right role group, you need to request access from another administrator. - Problem: Connection Timeout
Solution: Your remote session might time out after a while. To fix it, repeat the steps from prepare to use Compliance Search. - Problem: Misspelled cmdlet
Solution: I’ve seen New-ComplainceSearch more times than I’m willing to confess. I was even considering creating the New-ComplainceSearch alias for the right cmdlet. Maybe I’m the only one typing the cmdlets manually, but it doesn’t hurt to check your spelling if you do type a cmdlet. Also, you can always type in “New-Com” and tab your way to the right cmdlet. IntelliSense makes your life easier.
The search is still running
This error appears if you are too hasty or run searches with extremely 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 are searching only the relevant directories.
To check the status of Compliance Searches, run:
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 fix it, either use a new unique name, or run Set-ComplianceSearch instead.
Has anyone had success running Start-ComplianceSearch using a Service Principal?
I’ve followed the guide from https://learn.microsoft.com/en-us/powershell/exchange/app-only-auth-powershell-v2?view=exchange-ps and get error exactly reported here https://answers.microsoft.com/en-us/msoffice/forum/msoffice_other-msoffice_unknown-mso_subother/compliance-search-initialization-for-xxx-failed/a63e9591-cac9-4efa-897a-9aa2fd748c83?messageId=9eb4111b-b904-40b8-9d59-4dfaaa84fc76.
I’ve given service principal almost every privileged role available and have managed to get past the error above but not getting no results from compliance search. With my account I can run the same query with no issues.
If you’re using Conditional Access policies, that’s where I’d start checking if the service account has access to specific parts of Entra ID blocked.
Another possible blocker is the recent rollout of mandatory MFA for admin portals. But that would most probably block you at sign in.
I’d also take a look if there’s anything of value in the Purview portal – maybe there’s something that PowerShell didn’t return.
Anyway, if you do manage to get this to work, I’d be happy to learn what caused this issue.
Thanks for the guide!
Im running into issues with the last command Start-ComplianceSearch
Start-ComplianceSearch -Identity $searchName
Start-ComplianceSearch: |Microsoft.Exchange.Configuration.Tasks.ThrowTerminatingErrorException|Unable to execute the task. Reason: Compliance search initialization for “Monthly Sales Meetings Automation” failed with exception: Object reference not set to an instance of an object..
When i go to the compliance center i can see the search has failed with an error: The search job has failed.
Internal server error occurred. Please try again later. (CS019-001)
I can then rerun the search from the compliance center, which is successful.
It seems that, for some reason, the search task cannot find the location for the search: “Monthly Sales Meeting Automation”. Could you share what was the exact New-ComplianceSearch syntax you’ve used? If it’s an inactive mailbox, you need to prepend it with a period.
I’m running into an issue with New-ComplianceSearch and Start-ComplianceSearch where (with all permissions/roles confirmed) it creates the search, runs it, and results in 0 items. Then I go to the Actions button, and click Edit, delete the default search Condition, then run Start-ComplianceSearch again and it works fine. How do I delete that search condition from PowerShell?
What is the search condition you delete? You can try specifying a very general condition, like
-ExchangeLocation allto overwrite the default one.Hi, i have a problem and idk why, because in my opinion i have required permissions.
A have role Discovery Management and also Mailbox Import Export.
A can connect to Connect-IPPSSession with no error, but if I try use command
>>Get-eDiscoveryCaseAdmin
Get-eDiscoveryCaseAdmin: The term ‘Get-eDiscoveryCaseAdmin’ is not recognized as a name of a cmdlet, function, script file, or executable program.
Check the spelling of the name, or if a path was included, verify that the path is correct and try again.
>> Get-ComplianceSearch
Get-ComplianceSearch: The term ‘Get-ComplianceSearch’ is not recognized as a name of a cmdlet, function, script file, or executable program.
So i can’t use this command and i don’t know which permission i miss.
Can You help me ?
The error’s wording suggests either a permissions issue (recently added roles?) or that cmdlets weren’t downloaded correctly.
Try restarting your PowerShell console, then run a fresh
Connect-IPPSSessionand try the cmdlets that failed again.If that doesn’t change anything, try going to the Microsoft Purview admin center’s permissions tab: https://compliance.microsoft.com/permissions and check whether you can access it. If you can, see if you’re a part of the role group that includes the “Compliance Search” role. For example, an eDiscovery Manager will do.
I’m so looking for the replacement for this command:
Search-Mailbox -Identity [email protected] -SearchQuery ‘Subject:”aaabbbccc”‘ -DeleteContent
Can some please tell me how to translate this to the new-compliance search command? It’s driving me nuts.
Thanx
Currently, you’d use something along those lines:
New-ComplianceSearch "SearchName" -ExchangeLocation [email protected] -ContentMatchQuery 'subject:"aaabbbccc"' | Start-ComplianceSearch;New-ComplianceSearchAction -SearchName "SearchName" -purge -purgetype HardDelete
great blog but I have a problem:
I will use the command:
New-MailboxSearch -Name “TEST” -SourceMailboxes “test_user” -SearchQuery ‘Received:01/01/2022..12/31/2022’ -EstimateOnly
Start-MailboxSearch “TEST”
Get-MailboxSearch “TEST” | fl
I get the following error: (in German)
Die Aufgabe kann nicht ausgeführt werden. Ursache: Der Task kann nicht den Benutzer ermitteln, der den Task ausführt.
In Zeile:1 Zeichen:1
+ New-MailboxSearch -Name “TEST” -SourceMailboxes “testus …
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : InvalidOperation: (:) [], MailboxSearchTaskException
+ FullyQualifiedErrorId : [Server=MS1,RequestId=97ffe216-0b53-412b-9820-8fa33861cf13,TimeStamp=24.01.2024 13:16:10] [F
ailureCategory=Cmdlet-MailboxSearchTaskException] 94D11457
The user which perform this commadn is exchange administrator, is also added to “Discovery Management”
The ols version of search “Search-Mailbox” is running, but we have more the 10000 items at mailboxes.
The script is running on Exchange 2016 on premise.
Do you have any idea?
Since you are using Exchange 2016, I would recommend going with the Search-Mailbox cmdlet and dividing the search into several batches, e.g. by using date ranges in the query.
“A parameter cannot be found that matches parameter name ‘Purge'”
Does this not work for Exchange Online?
This looks like an issue with insufficient permissions. Make sure that you assign yourself the required roles, as explained in this article. Once done, allow some time for the changes to propagate and reset your connection to Exchange Online.
I tried with couple of users by giving them Compliance search management permission and discovery management permission. I also check the Set-Executionpolicy is set as RemoteSigned, however getting below error while running New-Compliancesearch command. I check on 2 of my servers and same issue. Earlier same cmdlet was working fine to delete the spam emails.
PS] C:\Windows\system32>New-ComplianceSearch -Name “Removespamt21_6_23” -ExchangeLocation all -ContentMatchQuery ‘subject:”Thông báo tài kho?n, Xác minh tài kho?n c?a b?n.”‘
Unable to execute the task. Reason: Failed to retrieve executing user. Please try again later.
+ CategoryInfo : WriteError: (:) [], ComplianceJobTaskException
+ FullyQualifiedErrorId : [Server=TCT-EXCH04,RequestId=07423480-7266-4749-b249-060cb8f4a2f8,TimeStamp=6/21/2023 3:37:43 AM] [FailureCateg
ory=Cmdlet-ComplianceJobTaskException] B4A55527
+ PSComputerName : tct-exch04.vp.tct.vn
Based on the error message, it looks like there is a problem with the admin account performing the action. Either the permissions have not been applied properly, or the admin does not have a mailbox and you need to assign an Exchange Online license to him.
I can’t figure out if I have permission to do this.
When I try the Add-RoleGroupMember example, I get:
The operation couldn’t be performed because object ‘Discovery Management’ couldn’t be found on ‘FfoRecipientSession’.
If I can run the New-ComplianceSearch and Start-ComplianceSearch cmdlets, but Get-ComplianceSearch returns 0 hits. I don’t know if my query is wrong or if I just don’t have the permission needed…
Try checking the permissions directly in the Microsoft Purview compliance portal: https://compliance.microsoft.com/ . But since you’re actually able to run the cmdlets, you should have the right permissions – the query might be at fault.
Im my case i added email box to my admin account, in other way i had access error even with delivery group membership.
++ We run the command which consisted the parameters which cx requires:
New-ComplianceSearch -Name “Test76″ -ExchangeLocation all -ContentMatchQuery ‘(subject:”Test”) AND (Received:6/26/2019..6/28/2021) AND (From:[email protected])’
++ We received the desired output Mentioned towards end of notes
++ We ran the
New-ComplianceSearchAction -SearchName “Test76” -Purge -PurgeType SoftDelete command to purge the emails and we succeeded in deleting the emails from mailbox
++ One concern that cx raised was, in the output received from command:
Get-ComplianceSearchAction -Identity Test76_purge | fl > C:\temp\Test76_purge.txt
We are not getting the location information (Highlighted) indicating from which mailboxes the email deleted
Location: [email protected], Item count: 24, Total size: 584856,
Location: [email protected], Item count: 1, Total size: 23282,
Location: [email protected], Item count: 1, Total size: 22054,
Location: [email protected], Item count: 1, Total size: 21644,
Output Post Deletion:
{Location: ; Item count: 10; Total size: 203950; Failed count: 0; ,
Location: ; Item count: 1; Total size: 23282; Failed count: 0; ,
Location: ; Item count: 1; Total size: 22054; Failed count: 0; ,
Location: ; Item count: 1; Total size: 21644; Failed count: 0; }
++ Cx needs this “Location” information to get clear picture from which mailboxes the mails are getting deleted
Can we get this location information by any switch or parameter
Try adding the -Details switch to Get-ComplianceSearchAction
This is all well and good, but that “get-credential” command in the connection script doesn’t work if your org has MFA set up.
… I’m not the smart kind, does anyone know how to get the MFA authentication to work with this type of script?
When it comes to connecting to Exchange Online, use Connect-ExchangeOnline without the -credential parameter. It will open a standard sign in pop-up. I’ve updated the cmdlets in the article, so that they work with MFA enabled, too.
“New-ComplianceSearchAction is not intended for a mass cleanup of mailboxes, as it only deletes 10 items per mailbox at a time.”
If CodeTwo would add functionality for emptying mail boxes that would be a killer feature.
After creating a New-ComplianceSearch object in powershell, I used to be able to open the Compliance admin center from the M365 admin center, click on show all, and view my compliance searches. Now I can only find Content Search, which is not the same thing. Any idea where they moved it this week?
All Compliance searches can be currently found under the Content search tab in the Compliance Center (https://compliance.microsoft.com/contentsearchv2?viewid=search), there doesn’t seem to be any other place they appear at.
eDiscovery Management, but you already know that by now :)
You must be Org Management role or assigned to Search and Purge role group to delete messages
Also, you must use the SCC PS module to delete, otherwise nothing happens.
You have to be in E-Discovery Manager role or Search Compliance role group to create the content search.
More than 10 messages, and it becomes much more difficult.
That’s why I still use Search-Mailbox for deleting emails. Hope it doesn’t stop working all of a sudden.
The new cmdlet will search OneDrive and SharePoint sites. Is there a way to delete files found in those places? I get an error stating that Purge does not support the SharePoint or OneDrive workload.
Unfortunately, neither those cmdlets, nor the compliance search via UI can be used to delete files from SharePoint or OneDrive.
Hi,
Can you also do the compliance search in the GUI/admin panel, and then call the name through powershell to delete? Or do you need to do everything through Powershell?
Kind regards,
Daan
Hi Daan,
Yes, you can Admin Panel to run a compliance search and then delete its results with PowerShell.
I tried the the command without an error
However it doesn;t delete emails.
I understand it only delete 10 of email each time.
So i repeat the process 5 times
and thought the spam mail has been deleted, i ran query again and bam 142 items still.
Have you used the -PurgeType HardDelete attribute? If not, those items are only soft-deleted.
great blogs but here I ran into a problem
PS C:\temp> Add-RoleGroupMember “Discovery Management” -member [email protected]
tiggers
The operation couldn’t be performed because object ‘Discovery Management’ couldn’t be found on ‘FfoRecipientSession’.
+ CategoryInfo : NotSpecified: (:) [Add-RoleGroupMember], ManagementObjectNotFoundException
+ FullyQualifiedErrorId : [Server=DB5EUR03WS010,RequestId=3e29214f-2606-4a24-a404-428677771cda,TimeStamp=28.05.202
0 16:05:23] [FailureCategory=Cmdlet-ManagementObjectNotFoundException] EF80F707,Microsoft.Exchange.Management.Rbac
Tasks.AddRoleGroupMember
+ PSComputerName : eur03b.ps.compliance.protection.outlook.com
All other commands OK
Can you see what is wrong her?
It looks like you might not have sufficient permissions to runt this cmdlet. See if you can add members to this role group using Exchange Admin Center, or ask a global admin to assign permissions.