Using the Search-Mailbox PowerShell command – Introduction | Part 1#5 5/5 (2) 16 min read

The current article series deal with a very useful and powerful PowerShell command named – Search-Mailbox . I relate to the Search-Mailbox PowerShell command as a “Swiss Knife” because we can use the Search-Mailbox PowerShell command for many types of scenarios.

What does the Search-Mailbox PowerShell command do?

The Search-Mailbox PowerShell command as the name suggests, serve as a tool for the Exchange administrator to perform a search in Exchange mailboxes (or multiple mailboxes) for specific mail items.

The term “mail items” relate to any type of mailbox items such as – E-mail message, calendar meeting, contact, task and so on.

The Search-Mailbox PowerShell command has four distinct and special characters.
1. The search result

Associatively, we can assume that the term “Search Results” translates into some kind of index, which lists all the search findings (Log file etc.). The interesting thing about the Search-MailboxSearch Results” is that the “Search Results” realized as a copy of the original mail items that answer our search query.

For example, if we use the Search-Mailbox PowerShell command to look for E-mail message with a specific text string in Bob’s mailbox, the Search-Mailbox PowerShell command enables us to copy the mail items that answer our query (the “Search Results”) to another store (the Target mailbox which will be discussed later).

2. The “action” that can be implemented when using Search-Mailbox

As mentioned in the former section the Search-Mailbox PowerShell command can help us to look (search) for specific mail items stored in Exchange mailbox and copy this mail item to another store (another Exchange mailbox).

An addition “action” that can be implemented by the Search-Mailbox PowerShell command is a very interesting and powerful action – Deletion of mail items (Deletion of the “Search Results”).

Besides of a new Office 365 PowerShell command named – New-ComplianceSearchAction, the Search-Mailbox PowerShell command is the only command that enables Exchange administrator to “remove” (Delete) specific mail items from Exchange mailbox or Multiple Exchange mailboxes.

Note – you can read more information about how to deleted mail items using the PowerShell command
New-ComplianceSearchAction in the article – Search for and delete email messages in your Office 365 organization – Admin Help

3. he Exchange mailbox “space”

The Search-Mailbox PowerShell command enabled us to define specific “location” of the Exchange mailbox in which the search action will be implemented.

For example, we can instruct the Search-Mailbox PowerShell cmdlet to perform a search only in the special hidden mailbox folder named – the Recovery mail folder (the Dumpster) that serves as a dedicated store for Soft Deleted and Hard Deleted mail items.

4. The search query

The Search-Mailbox cmdlet enable us to define almost every possible parameter for defining our search query such as – sender, recipient, date, the type of the mail item, specific Text string and much more.

In addition, we can use a very sophisticated search query that combines many different types of filters such as – show only calendar items from a specific date that have a specific subject.

Search-Mailbox command structure

The Search-Mailbox cmdlet consists of three parts

  • Part A – In this part, we define the “objects” that we want to address. The object is Exchange mailbox
  • Part B – In this part, we define the specific characters of the search query that we need to perform. For example, search for mail items that include a specific text string.
  • Part C – In this part, we define the specific “action” that we want to apply to the Search Results we get from the former parts.

Search-Mailbox command structure -01

Search scope

The term “Search Scope” relates to the Exchange mailboxes that we “address” when we perform the search. The specific mailbox or the mailboxes defined as “Source Mailbox.”

Mailbox Search Scope -02

Scenario 1 – Searching mail items | Single Exchange mailbox

In this scenario, the PowerShell command syntax is implemented as follows:

Scenario 2 – Searching mail items | Multiple Exchange mailboxes

In this scenario, the PowerShell command syntax is implemented by “declaring” the search scope, meaning the Exchange mailboxes for which the search task will be carried out.

Then we “pipe” the Exchange mailbox group to the Search-Mailbox PowerShell command.

There many options that we can use for defining a specific “group” of Exchange mailboxes.

Example 1 – Perform Multiple mailbox search | All types of Exchange mailboxes

For example, to perform a search for mail items in all existing Exchange mailboxes, we can use the following command syntax:

Example 2 – Perform Multiple mailbox search | All Exchange USER mailboxes

Example 3 – Perform Multiple mailbox search | All Exchange Shared mailboxes

Example 4 – Perform Multiple mailbox search | All Exchange Room mailboxes

Example 5 – Perform Multiple mailbox’s search | Exchange Mailboxes – members in Distribution Group

In this scenario, we want to perform a search by defining a “group of Exchange mailboxes” which “belong” (members) to a specific Distribution Group.

Search Query (Search filter)

The Search-Mailbox PowerShell cmdlet supports very powerful syntax that defines the Search Query (the Search filter or the Search criteria).

The search Query is implemented by using the parameter – SearchQuery + the specific filter that we want to use.

The search filter can be implemented as a simple search query or, as an advanced search query that is written by KQL language.

Note – in case that you want more information about the KQL language in the following articles:

Search FILTER -03
Example 1 – Search for a specific type of mail items

We can define a search filter that looks only for specific types of mail items.

For example,

To search only calendar items, we can define a search query using the following syntax:

To search only Contacts items, we can define a search query using the following syntax

Example 2 – Search for a mail item that sent from a specific sender or sent to a specific recipient

In case that we want to filter the search result by defining a specific sender or specific recipient, we can use the following syntax

Search for mail items sent by a specific sender:

Search for mail items, sent to a specific recipient:

Example 3 – looking for mail items that sent in a specific date

We can perform a search query that relates to the “date” of mail items.

For example

Search for mail items sent on a specific date:

Search for mail items sent on a specific date range:

Example 4 – looking for mail items with attachments

In case that the information that we look for is mail items with attachments, we can use the following search query:

Search for mail items that, include a specific attachment (attachment file name):

Search for ANY mail items that, include an attachment:

Example 5 – looking for mail items with a specific text string

To search Emails with Text String in mail SUBJECT, we can define a search query using the following syntax

To search Emails with Text String in mail BODY, we can define a search query using the following syntax

Search-Mailbox cmdlet and the required “action”

We can define three types of “actions” that the Search-Mailbox PowerShell command will perform:

  1. Create a Log File – this option can be used in case that we don’t want to get a copy of the mail items (the search result) but instead, only a “report” (Log) that include information on the mail items that were found.
  2. Copy the mail items (the search results) to “another” mailbox – this option can be used in a scenario in which we want to recover or save mail items that appear in the search result.
  3. Delete the mail items that were founded – this option can be used in a scenario in which we want to “destroy” (delete) the specific mail items. For example, a scenario in which our organization was attacked by a virus, and we want to locate all the infected mail items and delete them.

In addition, we can choose to “combine’” couple of “actions.” For example, we can define an action in which the mail items will be deleted from the source mailbox, but in addition, a copy of the mail items will be saved in a “target mailbox” + create a Log file that includes information about each mail items that appear in the search results.

The required Action -01

The concept of “SOURCE mailbox” and “TARGET mailbox”

An important concept of the Search-Mailbox PowerShell cmdlet is the concept of:

  1. Source Mailbox
  2. Target Mailbox
  3. Target Folder

As mentioned, most of the time the action of “Search Results” is translated to a Log file or, to a copy of the mail items that was found in the search process.

To be able to “store” the “Search Results” (the Log file or the mail items that were found), we need to define a “target store” meaning – Target Mailbox.
In addition, we need to define a Target Folder that will be created, and that will contain the search results.

The Search-Mailbox cmdlet will need to “know” – what is the Source Mailbox, what is the Target Mailbox (that will store the search results) and what is the name of the Target Folder.

Target Folder

Given that we provide the name of the Target Folder name, the Search-Mailbox cmdlet will create this NEW folder in the Target Mailbox.

An example of the PowerShell syntax that we use for defining these “entities” could be:

The concept of – Source mailbox and Target Mailbox -02

The target Folder naming convention and structure

As mentioned, the Search-Mailbox cmdlet creates the Target folder (based upon the Target Folder name whom we provide as part of the PowerShell command) in the Target Mailbox. The Target Folder serves as a “store” for the search results, and have a specific hierarchy.

In the following diagram, we can see the structure of the Target Folder.

The Target Folder structure and hierarchy

Target Folder provided name

This is the name whom we provide as part of the Search-Mailbox command mandatory parameters.

Mailbox Display name + current search date

“Under” the name of the Target Folder, Search-Mailbox cmdlet creates the following hierarchy:

The source mailbox “Display name” + the current search time

The “folder name” that stores the search result is built from a combination of the Source mailbox display name + the current search time.

Notice that the “Time” that appears as part of the folder name considers as “GMT +0”.
The meaning is that in most of the scenarios, the search results “time” that appears as part of the folder name is a different time than your current \local time.

In case that you want to adjust the time to your local time zone, you will need to add or subtract the hours based on your local GMT.

For example, my time zone is GMT+3

In the following screenshot, we can see that the time that is mentioned is 10:13

In my scenario, the “real time” is 13:13 (10:13 + 3 hours).

Search-mailbox results folder name -02

The folder name – Primary mailbox

Search-Mailbox cmdlet creates a folder named – Primary mailbox.

This term relates to the “standard user mailbox” which defines as – Primary mailbox.

The reason that the Search-Mailbox cmdlet refers uniquely to the standard mailbox is because that theoretically, an Exchange user can have additional mailbox or a secondary mailbox which describes as the Archive mailbox.

Under the Primary mailbox, we can find the search result (a copy of the original mail items from the Source Mailbox). The Search-Mailbox cmdlet will keep the same folder hierarchy as it appears in the “source mailbox.”

Recoverable items

As mentioned, one of the most powerful abilities of the Search-Mailbox cmdlet is, the ability to search and “export” (copy) mail items stored in the Recovery mail folder (Dumpster).

In case that the search results include mail items that were stored in the Recovery mail folder (Dumpster), a new folder named – Recoverable items will be created.

Note – the mailbox owner cannot see the Recovery mail folder (Dumpster) because this is a hidden folder. Only the Exchange administrator who performs the search has the “privilege” to view this folder and the folder content as part of the search results that stored in the Target Mailbox (in the Target folder).

The folder name – Archive mailbox

This folder name “appears” only in a scenario in which the Source Mailbox has Archive (additional mailbox).

In this case, the Search-Mailbox cmdlet will store the search results that were found in the Source Mailbox archive

Source mailbox “space” or “scope”

In this section, I would like to briefly review that way that the Search-Mailbox cmdlet relate to the source mailbox “space.”

Search-Mailbox cmdlet define the of Exchange mailbox “space.”

  1. The Primary mailbox space.
  2. The Recovery mail folder (Dumpster) space.
  3. The Archive mailbox space.

mailbox space - 03

By default, the Search-Mailbox cmdlet will look (search) for mail items in all three parts above.

In some scenarios, we will need to instruct the Search-Mailbox cmdlet to “ignore” one of those “spaces” or to “concentrate” only in a specific “space.”

Example 1 – Perform a search only in the Recovery mail folder (SearchDumpsterOnly)

For example, a scenario in which we need to recover mail items that were Soft Deleted or Hard Deleted by the user. In this case, we want to define a very specific mailbox scope – the Recovery mail folder (Dumpster).

To restrict the search scope only for mail items stored in the recovery mail folder (defined also as the Dumpster), we can use the following syntax:

Example 2 – Perform a search only in the Recovery mail folder (SearchDumpsterOnly)

In this case, we want to perform a mailbox search, but we don’t want that the search will run on the Recovery mail folder (Dumpster) of the Source Mailbox.

To exclude the Recovery mail folder (Dumpster) from the search results, we can use the parameter SearchDumpster:$False

For example:

Note – in case that you want more information about the “Recovery mail folder” you can read the article – Recover deleted mail items in the Exchange Online environment | Single item recovery | 2#7

Example 3 – Perform a search only in the primary mailbox

In case that the user has an archive mailbox, and we want to exclude the Archive Mailbox from the search process, we can use that parameter DoNotIncludeArchive

For example:

Search-Mailbox cmdlet and required permissions

Using the Search-Mailbox cmdlet for “snooping” Exchange mailboxes require a special permission because from the “data privacy point of view,” we are looking at a private user data. In case that we use the Search-Mailbox cmdlet for deleting mail items, we are deleting private user data.

Attached a quotation from Microsoft’s article, about the required permissions that need to be assigned to the Exchange administrator who perform the search (or the deletion) by using the Search-Mailbox cmdlet:

You need to be assigned both of the following management roles to search for and delete messages in users’ mailboxes:

  • Mailbox SearchThis role allows you to search for messages across multiple mailboxes in your organization. Administrators aren’t assigned this role by default. To assign yourself this role so that you can search mailboxes, add yourself as a member of the Discovery Management role group. See Assign eDiscovery permissions in Exchange.
  • Mailbox Import ExportThis role allows you to delete messages from a user’s mailbox. By default, this role isn’t assigned to any role group. To delete messages from users’ mailboxes, you can add the Mailbox Import Export role to the Organization Management role group. For more information, see the “Add a role to a role group” section in Manage role groups .
[Source of information – search for and delete messages – Admin help]

To assign the roles directly to a user via PowerShell, run the following PowerShell commands:

Search-Mailbox cmdlet and limitation

The Search-Mailbox cmdlet have two limitations that we should know about.
1. Maximum “source mailboxes.
The Search-Mailbox cmdlet can perform a multiple mailbox searches for a maximum of 10,000 mailboxes.

You can search a maximum of 10,000 mailboxes using the Search-Mailbox cmdlet. If you’re an Exchange Online organization and have more than 10,000 mailboxes, you can use the Compliance Search feature (or the corresponding New-ComplianceSearch cmdlet) to search an unlimited number of mailboxes. Then you can use the New-ComplianceSearchAction cmdlet to delete the messages returned by a compliance search. For more information, see Search for and delete email messages from your Office 365 organization.

[Source of information – search for and delete messages – Admin help]

2. The maximum search results when using search queries
When we use the Search-Mailbox cmdlet + a search query, meaning using the –SearchQuery parameter, the results are limited to a maximum of 10,000 results.

When we run the Search-Mailbox cmdlet, the following warning appears:

WARNING: The Search-Mailbox cmdlet returns up to 10000 results per mailbox if a search query is specified. To return more than 10000 results, use the New-MailboxSearch cmdlet or the In-Place eDiscovery & Hold console in the Exchange Administration Center.


The Search-Mailbox | PowerShell scripts series

The Search-Mailbox PowerShell cmdlet is very powerful and can be used for a various type of administrative scenarios. For this reason, I have created a “series” of PowerShell scripts, that will help you to “enroll” the Search-Mailbox PowerShell cmdlet for implementing different type of tasks:

Search for mail items using the Search-Mailbox PowerShell cmdlet (1#4)

A PowerShell menu script that is used for – performing a search in a single Exchange Online mailbox, by using various types of filters such as – specific text, specific date, a specific type of mail items (calendar, contact, etc.), mail with attachment and more.
Searching hidden Email addresses Using PowerShell - Office 365 - Part 11-13


Recover mail items using the Search-Mailbox PowerShell cmdlet (2#4)

PowerShell menu script, that is used for – Recovers mail items that are stored in the Recovery mail folder (Exchange Online Mailbox Dumpster). The PowerShell script, will help you to Recover all the content of the recovery mail folder or, use a search filter that will recover only specific mail items that answer a specific character such as – specific text, specific date, specific type of mail items (calendar, contact, etc.), mail with attachment and more.
Using the Search-Mailbox PowerShell command - Recover mail abc- Part 3-5u


Delete mail items – Multiple Exchange mailboxes (Bulk) using PowerShell (3#4)

PowerShell menu script, that is used for – performing a Deletion of specific mail items from multiple Exchange Online mailboxes (bulk mode). The “Deletion” of this mail item, is implemented by selecting a “search filter” that will delete only mail items that have specific characters such as – specific text, specific date, a specific type of mail items (calendar, contact, etc.), mail with attachment and more.

Search and Delete mail items from Multiple Exchange mailboxes Bulk using Search-Mailbox PowerShell cmdlets-Part 4-5


Search and Delete mail from Single Exchange mailboxes using PowerShell (4#4)

PowerShell menu script, that is used for – performing a Deletion of specific mail items from a single Exchange Online mailbox.
The “Deletion” of this mail item, is implemented by selecting a “search filter” that will delete only mail items that have specific characters such as – specific text, specific date, a specific type of mail items (calendar, contact, etc.), mail with attachment and more.
Search and Delete mail items from the Exchange mailbox using Search-Mailbox PowerShell cmdlets - Single mailbox-Part 5-5

Restore Exchange Online mailbox | Article series index

Now it’s Your Turn!
It is important for us to know your opinion on this article

Related Post

Please rate this

Eyal Doron on EmailEyal Doron on FacebookEyal Doron on GoogleEyal Doron on LinkedinEyal Doron on PinterestEyal Doron on RssEyal Doron on TwitterEyal Doron on WordpressEyal Doron on Youtube
Eyal Doron

Share your knowledge.

It’s a way to achieve immortality.

Dalai Lama


Leave a Reply

Your email address will not be published. Required fields are marked *