How to search for and delete email messages in Exchange Online

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”.

Get compliance search results

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.

  1. 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

Daniel Bradley

My name is Daniel Bradley and I work with Microsoft 365 and Azure as an Engineer and Consultant. I enjoy writing technical content for you and engaging with the community. All opinions are my own.

Leave a Reply