How to Use Search-Mailbox in Powershell

The Search-Mailbox cmdlet in PowerShell is a quick way for Exchange admins to search, retrieve, and delete emails from user mailboxes directly.

Ideal for managing compliance needs or quickly finding specific messages, this cmdlet helps keep mailboxes organized without the need for manual searches. Here’s how to use Search-Mailbox, set it up and make the most of its features!

What is Search-Mailbox PowerShell?

The Search-Mailbox cmdlet in PowerShell is used for searching a mailbox in on-premises Exchange environments to locate specific emails based on defined criteria, such as keywords or date ranges.

The command allows administrators to copy search results to a target mailbox, delete emails from the source mailbox, or perform both actions. It's normally used to clean up mailboxes, recover items or manage compliance by moving or removing specific email content.

Take a look at the syntax of Search-Mailbox and a brief explanation of its meaning:

• -Identity: Specifies the mailbox to search.
• -Confirm: Prompts for confirmation before executing the command.
• -DeleteContent: Deletes the found content from the source mailbox.
• -DomainController: Defines the domain controller to use for Active Directory operations.
• -DoNotIncludeArchive: Excludes the archive mailbox from the search.
• -Force: Suppresses any confirmation prompts.
• -IncludeUnsearchableItems: Includes items that couldn't be indexed by Exchange in the search.
• -SearchDumpster: Includes the Recoverable Items folder in the search.
• -SearchDumpsterOnly: Searches only the Recoverable Items folder.
• -SearchQuery: Specifies the search query or keywords to find specific content.
• -WhatIf: Simulates the command's actions without making any changes.

What Can You Use the Search-Mailbox PowerShell Command For?

Let’s see three practical use cases for the Search-Mailbox cmdlet that can add value in an Exchange environment:

1. Targeted Email Deletion for Compliance: You can use Search-Mailbox to locate and delete emails containing sensitive or outdated information, helping maintain compliance with company policies and regulatory standards.
2. Bulk Cleanup of Inactive Accounts: When deprovisioning a former employee's account, you can use Search-Mailbox to move relevant emails to an archive mailbox, ensuring important information is retained while clearing unnecessary content.
3. Data Recovery from Recoverable Items Folder: If a user accidentally deletes important emails, Search-Mailbox allows you to search within the Recoverable Items folder, restore specific emails, or move them to a designated folder, preventing data loss without restoring the entire mailbox.

3 Prerequisites to Use the Search-Mailbox Command in PowerShell

To use the Search-Mailbox cmdlet, you'll need to meet three main prerequisites:

1. Role Assignment: Make sure that you have the Mailbox Search or Mailbox Import Export roles assigned to your account. By default, these roles aren’t assigned to any role groups, so you might need to add one of them to a role group like Organization Management. Importantly, only the Mailbox Import Export role grants access to the -DeleteContent parameter.
2. On-Premises Exchange Environment: This cmdlet is available only in on-premises Exchange Server environments (Exchange 2010, 2013, 2016, or 2019). For cloud-based environments, use New-ComplianceSearch instead - we’ll talk a bit more about this later on.
3. Access to Target Mailboxes: If you’re copying search results, confirm you have appropriate permissions on the target mailbox, as the cmdlet requires access to save or log search results in the specified destination mailbox.

How to Use Search-Mailbox in PowerShell in Just 4 Steps

Using Search-Mailbox is quite easy, and we’ll show you how to do it in just four steps.

Step 1: Connect to Exchange PowerShell

Before using Search-Mailbox, you need to connect to the Exchange PowerShell environment. The connection process depends on whether you’re working with Exchange Online or an on-premises Exchange environment.

Use your credentials to connect to Exchange PowerShell, then proceed to the next step.

2. Ensure Proper Role Assignments

As mentioned earlier, the Search-Mailbox cmdlet requires specific roles to perform certain actions, particularly for operations involving message deletion. Two main permissions are required:

• Mailbox Search Role: Provides permissions to search mailboxes.
• Mailbox Import Export Role: Needed to delete messages using the -DeleteContent parameter.

To assign these roles, use the New-ManagementRoleAssignment command as shown below:

This step is critical as these roles are not assigned by default to any user groups, even the Organization Management group.

Step 3: Define the Target Mailbox and Search Criteria

With role permissions set, the next step is defining which mailbox to search and setting the search criteria. You’ll use the -Identity parameter to specify the mailbox and -SearchQuery to narrow down your search.

For example, let’s look at the following scenario. To search for all emails with “Simon Office” in the subject of James’s mailbox, do this:

In this case, SearchQuery supports Keyword Query Language (KQL), enabling more refined searches.

Now, let’s see another example. To find emails sent by “[email protected]” between specific dates, do this:

This command searches John’s mailbox for emails received from "[email protected]" during the entire year of 2024.

Step 4: Choose the Action: Copy, Delete, or Log Results

With Search-Mailbox, you can choose to copy messages to a target mailbox, delete messages from the source mailbox, or just log the search results.

• Copying Messages to a Target Mailbox: Use the -TargetMailbox and -TargetFolder parameters to store results in a discovery mailbox, which is helpful for eDiscovery purposes.
• Deleting Messages from a Mailbox: To delete specific messages, add the -DeleteContent switch. Be cautious, as this action permanently deletes the messages.

And that’s all you need to know to effectively use Search-Mailbox in PowerShell!

Search-Mailbox Not Working in PowerShell? Do This

If you encounter issues while executing the command, try the following:

1. Error: "The term ‘Search-Mailbox’ is not recognized"

Cause: This error typically occurs in cloud-based (Exchange Online) environments, where Search-Mailbox is deprecated.

Solution: Use the New-ComplianceSearch cmdlet and related eDiscovery cmdlets instead, which are designed for Office 365 and Exchange Online.

2. Error: "You don't have permissions to use the Search-Mailbox cmdlet"

Cause: The user account lacks the required Mailbox Search or Mailbox Import Export roles.

Solution: Assign the necessary roles to the user’s role group, such as Organization Management, through Exchange Admin Center or PowerShell.

3. Error: "Cannot delete content because DeleteContent parameter is not accessible"

Cause: The Mailbox Import Export role, which grants -DeleteContent access, is not assigned to the user.

Solution: Add the Mailbox Import Export role to your role group to enable deletion capabilities.

The Search-Mailbox cmdlet is an essential tool for Exchange administrators looking to streamline email management and ensure compliance.

By getting to know its features and best practices, you can make the most of this cmdlet to improve your email management. With the right approach, Search-Mailbox can save you time and effort, letting you focus on more important goals for your organization.