The need to find specific emails within your Exchange environment usually follows a mistake made by one of your users. It can, however, be a useful feature to remove out-of-date informational emails that have been sent to your staff or to handle compliance-based requests.
Using the Exchange Online PowerShell cmdlets we can craft specific commands to search for emails across a single mailbox or all of our mailboxes and then we can manipulate that email, such as deleting it.
In this post, I am going to show you how to search for and delete email messages in your organisation using PowerShell.
Prerequisites
Make sure you have installed the Exchange Online PowerShell module and have connected to your environment. If you are unsure how to do this, follow my guide here: How to connect to Exchange Online with PowerShell.
Assigning the correct permissions to perform the task
Although with global administrator access you will be able to run a compliance search and delete the results, you may still encounter some common errors when trying to preview your search results before deletion, for example:
A parameter cannot be found that matches parameter name ‘preview’.
+ CategoryInfo : InvalidArgument: (:) [New-ComplianceSearchAction], ParameterBindingException
+ FullyQualifiedErrorId : NamedParameterNotFound,New-ComplianceSearchAction
+ PSComputerName : gbr01b.ps.compliance.protection.outlook.com
To resolve the error, you must be assigned either the eDiscovery Manager role or eDiscovery Administrator role. This can be done through the Microsoft Purview admin center, as follows:
1. On the left-hand menu, select Permissions.
2. Under the Microsoft Purview solutions heading, select Roles.
3. Highlight eDiscovery Manager and a pop-out window will appear from the right.
4. Next to eDiscovery Manager, select Edit > Choose eDiscovery Manager > Add.
5. Select your account from the list and click Done > Save.
Connect to Security and Compliance PowerShell
Before you begin running any search commands, you must connect to security and compliance in Microsoft 365 through your PowerShell session. If you have already installed the ExchangeOnline module, run the following cmdlet and log in with the interactive prompt.
Connect-IPPSSession
How to search for and delete emails in a single mailbox
To search, we are going to use the New-ComplianceSearch cmdlet to first create our search query. This command will allow us to specify detailed parameters for our search to give accurate results. Here is an example search where I can find all emails within a mailbox with a specific subject.
$Search=New-ComplianceSearch -Name “Remove order notifications2” `
-ExchangeLocation [email protected] `
-ContentMatchQuery ‘(Subject:”Your Microsoft order on 09 October 2022″)’
There are many more parameters you can use to fine-tune your results, here are some options:
Find content that includes specific words:
-ContentMatchQuery “‘Order’ AND ‘October'”
Find content within a specific date range:
-ContentMatchQuery ‘(Received:09/01/2022 00:00..09/01/2022 23:59)’
Find content from a specific sender:
-ContentMatchQuery ‘from:”[email protected]”‘
Using logical operators to join search parameters:
-ContentMatchQuery ‘(from:”[email protected]”) AND (Subject:”order”) AND (Received:09/01/2022 00:00..09/01/2022 23:59)’
View your search status
Once you have successfully run the command to create your compliance search, you can use the GET command to view the status of the search.
Get-ComplianceSearch
As you can see from the below image, our search named “Remove order notifications2” is in the status “NotStarted”.
Start your search
To start the search we have to run the following command:
Start-ComplianceSearch -Identity $Search.Identity
As you can see, we have used the variable $Search which contains the information from the first command. Once the search is complete, it will show in the status column as ‘Completed’. Also, to specify a specific search to interact with, you can input the name of the search as follows:
Start-ComplianceSearch -Identity “remove order notifications2”
How to search for and delete emails in multiple mailboxes
You can apply the above login and scripts to search for emails in a specific mailbox and to all mailboxes in your organisation. All you need to do is specify ALL in the Exchange location parameter, as follows:
$Search=New-ComplianceSearch -Name “Remove order notifications2” `
-ExchangeLocation ALL `
-ContentMatchQuery ‘(Subject:”Your Microsoft order on 09 October 2022″)’
Specifying ALL, will ensure every mailbox is searched for your content query.
How to preview compliance search results in PowerShell
It is important that you preview the data you are going to delete first before you run the soft or hard delete action (which we will cover in the next segment).
You can use the following steps to preview your search results.
- Start by creating a new compliance search action with the following command:
New-ComplianceSearchAction -SearchName “remove order notifications2” -Preview
2. You can verify this by entering the following (The status will automatically enter ‘starting’, then will be ready once ‘completed’).
Get-ComplianceSearchAction
3. Once the status is Completed, run the following to preview the results.
Get-ComplianceSearchAction -Identity ‘PhishingSearch_Purge’ | Format-List -Property Results
OR
(Get-ComplianceSearchAction “remove order notifications2_preview”| Select-Object -ExpandProperty Results).Split(“;”)
Delete emails from Exchange Online
Once you have fine-tuned your content search query and are happy with the results preview, the final command to run is the delete action.
There are 2 options when you are running the delete actions, those are soft delete and hard delete.
- Soft Delete – Removes the items from the users deleted items, however, it remains in their second-stage recycle bin
- Hard Delete – Remove the item complete from their mailbox and recycle bins.
To delete the items, run the following command:
New-ComplianceSearchAction -SearchName “remove order notifications2” -Purge -PurgeType SoftDelete
OR
New-ComplianceSearchAction -SearchName “remove order notifications2” -Purge -PurgeType HardDelete