Petri Newsletter Sign-up
Office 365 Insider

Here at Petri.com, we get IT — and so can you. Subscribe today to stay informed and knowledgeable regarding the latest on IT.

    See All Petri Newsletters

    Microsoft Deprecating Exchange Online's Search-Mailbox Cmdlet

    Posted on by Tony Redmond in Exchange Online, Exchange Server, Office, and Office 365

    I see Microsoft has started to flag the deprecation of the Search-Mailbox cmdlet (Figure 1) in a PowerShell banner anytime the cmdlet is run. The banner comes with a recommendation to use Office 365 content searches (New-ComplianceSearch) instead.

    PowerShell gives a Search-Mailbox deprecation notice
    Figure 1: PowerShell gives a Search-Mailbox deprecation notice (image credit: Tony Redmond)

    You’ve got to admire Microsoft’s optimism that now is a good time to deprecate Search-Mailbox. They’ve been trying to get rid of the cmdlet since the introduction of eDiscovery searches in Exchange 2010 but have never gone quite so far as to flag the intention in public. Until now.

    Old-Fashioned but Powerful

    On the surface, there shouldn’t be a problem. Search-Mailbox is a cranky old-fashioned cmdlet that isn’t particularly easy to use. Search-Mailbox can only process mailboxes and knows nothing about the other data sources inside Office 365. It has no GUI to make searches easy to build. But Search-Mailbox does one thing very well: it finds and removes mailbox items better than other tools currently do. For this reason, Search-Mailbox is highly valued by administrators who need to remove spam and malware from user mailboxes or rescue the career of someone who sends out a message when they shouldn’t.

    Very Capable Office 365 Content Searches

    Office 365 content searches are very capable. They are highly scalable, can search through multiple data sources (Exchange Online mailboxes, Office 365 group mailboxes, Skype for Business conversations, Teams messages, To-Do, Sway, Forms (owned by Office 365 Groups), SharePoint Online, OneDrive for Business, and Exchange public folders), and come with a reasonable GUI to build search queries. Content searches also have a preview feature to sample a small set of search results to figure out if the search criteria are correct (Figure 2).

    Previewing items found by an Office 365 content search
    Figure 2: Previewing items found by an Office 365 content search (image credit: Tony Redmond)

    Deleting Items with Search Actions

    Once you find items with a search, you can apply actions to them. The direct comparison to Search-Mailbox is that you can set up a compliance search action to remove items from mailboxes using the Purge action. Only Exchange Online supports the purge action. You can’t use it to remove documents from SharePoint Online or OneDrive for Business.

    Purges can be hard, in which case the item is permanently removed from a mailbox, or soft, which means that the user can recover the deleted item. You can only set up and execute a purge search action through PowerShell. For example:


    Search actions usually complete quickly. You can then review the success of the action by running the Get-ComplianceSearchAction cmdlet and checking the content of the Results property. Unfortunately, this only tells you how many items Office 365 removed. It doesn’t tell you the mailboxes the items were removed from (which is why you make sure that the searches return the right items before purging anything). To find more information about the deleted items, you need to search the Office 365 audit log for the matching HardDelete or SoftDelete record (Figure 3).

    Information about purged messages in the Office 365 audit log
    Figure 3: Information about purged messages in the Office 365 audit log (image credit: Tony Redmond)

    Like any item removal in Exchange Online, an item won’t be permanently removed if it comes within the scope of an in-place or litigation hold. Instead, the item is kept in the Recoverable Items folder until the hold elapses.

    Comparing Search-Mailbox and Compliance Search Actions

    Table 1 summarizes the functionality available in Search-Mailbox and purges executed with compliance search actions. Both have their unique characteristics: compliance searches are faster and can process more mailboxes in a single operation but are limited to what they can remove from a mailbox. Search-Mailbox can focus on Recoverable Items or ignore a mailbox’s archive, while compliance searches can focus on a single target folder. The biggest difference is that Search-Mailbox can copy items to a target mailbox when it removes them from other mailboxes. You can export items with a compliance search, but you must do this separately and before you remove anything.

    Criterion Search-Mailbox Compliance Search Action
    Number of items that can be removed from a mailbox. All items are removed from mailboxes that match search query. Remove up to 10 items per mailbox that match search query.
    Number of mailboxes that can be processed in a single run. Maximum 10,000. Maximum 50,000.
    Speed Search-Mailbox is single-threaded, so processing multiple mailboxes can take some time. Multi-threaded distributed work makes content searches more scalable and faster.
    GUI to create search criteria. No Yes
    Process inactive mailboxes No Yes
    Copy items to another mailbox Yes No
    Ignore archive mailbox. Yes No
    Search Recoverable Items only Yes No
    Search specific folder in mailbox. No Yes
    Logging only Yes No (but preview and statistics are available).

    Table 1: Differences between Search-Mailbox and Content Search purges

    From an automation perspective, Search-Mailbox is easier to work with because it’s a single cmdlet. The process to remove items with a compliance search involves multiple steps. However, it’s plain sailing once you master those steps.

    I’m Not Worried If Deprecation Comes

    Would I be distressed if Microsoft carried out its threat to remove Search-Mailbox from Exchange Online? Not really. Compliance search actions can already do most of what Search-Mailbox does and it wouldn’t take much to tweak compliance searches to do all that Search-Mailbox does. If Microsoft fills those gaps, then I’m all for Search-Mailbox making its way to the great cmdlet wastebasket. And to make it even better, they could enable purging of documents with compliance search actions. Malware doesn’t just come in email!

    BECOME A PETRI MEMBER:

    Don't have a login but want to join the conversation? Sign up for a Petri Account

    Register