How to Use Microsoft 365 Compliance Search Purge Actions to Remove Exchange Online Messages

Hard Deletes for Office 365 Purges

As is often the case when you write for a moving target, I learned that Microsoft had upgraded the compliance search purge action to finally support hard deletes the day after we shipped the March 2019 update for Office 365 for IT Pros. The book is updated, but the topic is worth highlighting here.

Compliance Search Actions

Actions govern what happens when you run a content search. Normally, after creating a search, you execute an action to execute a preview search, followed by an export action when the search returns the set of items you need. Behind the scenes, the New-ComplianceSearch cmdlet sets up a search and the New-ComplianceSearchAction cmdlet associates an action with the search. The Start-ComplianceSearch cmdlet then starts the search.

Compliance Search Purge Actions for Exchange Online Only

The compliance search purge action is only supported for content searches executed against Exchange Online mailboxes. The Purge action is also only accessible to users who hold the Organization Management role for the compliance center. Up to recently, it was only possible to soft-delete mailbox items, which means that a user could recover the item. This is OK if you want to allow users to recover items deleted in error, but not if you want to permanently remove items like malware or messages sent in error. The Search-Mailbox cmdlet gets a lot of use in these scenarios because it is very good at removing mailbox items.

Microsoft didn’t say anything about upgrading the purge action to support hard deletes, and I only noticed the change when I looked at the documentation for New-ComplianceSearchAction for quite another reason. It’s nice how these unannounced changes pop up in the cloud, I guess.

In any case, if you use a hard delete purge action, Exchange Online moves the items into the Recoverable Items\Purges folder and marks them for permanent removal. The next time the Managed Folder Assistant processes the mailbox, it removes the items from the database and they are irrecoverable. While the items are in the Purges folder, they are invisible to the user.

Limited Purging

You can only create a purge action for a search with PowerShell. However, that’s not the big downside. Only ten items per mailbox can be purged in this manner. The limit is tied to the content search results, so if you wanted to remove 50 items from a mailbox, you’ll have to run five separate search and remove cycles to be sure that everything is found and deleted. By comparison, Search-Mailbox can process up to 10,000 items.

Microsoft is keen to emphasize that content search actions are not designed to perform mailbox clear-outs. Having a low limit per mailbox restricts the potential impact of administrator mistakes in the search query. It also forces administrators to construct search queries that are narrow rather than broad. In other words, you should use a search query that precisely identifies the exact message you want to remove rather than a query that casts a wide net and finds lots of items, including some that you don’t want to remove.

Compliance search actions by definition depend on being able to find indexed items. Unindexed items cannot be purged.

Hard delete purging (permanent removal) can’t be effective when litigation holds or in-place holds exist on a mailbox. If you want to permanently expunge all details of items from mailboxes, make sure that you remove any holds from the mailbox before starting. Soft delete purging (which allows users to recover deleted items) accommodates holds.

Using a Compliance Search Purge Action

First, create a content search with PowerShell or through the Microsoft Purview Compliance portal (the easiest approach). Make sure that the search finds the items that you want to remove and limit it to Exchange Online mailboxes. Now add the purge action by running the New-ComplianceSearchAction cmdlet to add the purge action and set the purge type to HardDelete:

New-ComplianceSearchAction -Purge -PurgeType HardDelete -SearchName "Search for Documents"

Confirm
Are you sure you want to perform this action?
This operation will make message items meeting the criteria of the compliance search "ACDSearch" completely
inaccessible to users. There is no automatic method to undo the removal of these message items.
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [?] Help (default is "Y"): y

Exchange Online notices that a purge action is specified and goes ahead to find the matching items using the query specified for the compliance search. It then purges the first 10 matching items found. The search should not take long (it’s only going to process 10 items), but you can check by running the Get-ComplianceSearchAction cmdlet. Note that the name of the action is formed by the search name, an underscore, and the name of the associated search. When the status is reported as Complete, the items are purged.

Get-ComplianceSearchAction -Identity "Search for documents_purge" | Format-Table Searchname, JobStartTime, JobProgress, Status

SearchName           JobStartTime         JobProgress Status
----------           ------------         ----------- ------
Search for Documents 15 Mar 2019 18:18:48         100 Completed

To check the effect of a purge, you can look at the folders in a user mailbox that you know held a message found by the search. Here we use the Get-ExoMailboxFolderStatistics cmdlet to retrieve the item count for the Purges folder. As items are purged, the item count in this folder should increase.

Get-ExoMailboxFolderStatistics -Identity Kim.Akers  -FolderScope RecoverableItems |?{$_.Name -eq "Purges"}| Format-Table Name, ItemsInFolder

Name      ItemsInFolder
----      -------------
Purges              701

We’ve published a script in our GitHub repository to show how to use a compliance search purge action to remove items from Exchange Online mailboxes. Hopefully, it will help you understand and implement the technique.

---

For more information about content searches, see Chapter 20 of the Office 365 for IT Pros eBook. The Search-Mailbox cmdlet is covered in Chapter 6.