Using the Search-Mailbox PowerShell command – Introduction | Part 1#5

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.

Connect to Exchange Online PowerShell

To be able to run the PowerShell commands specified in the current article, you will need to Connect to Exchange Online PowerShell.

Start Windows PowerShell as administrator and run the cmdlet Connect-ExchangeOnline.

Connect-ExchangeOnline

What does the Search-Mailbox PowerShell command do?

The Search-Mailbox PowerShell command as the name suggests serves 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-Mailbox “Search 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 previous 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.

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. The 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 enables 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” we want to apply to the Search Results we get from the previous parts.

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

Scenario 1 – Searching mail items | Single Exchange mailbox

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

Search-Mailbox <Source Mailbox> -SearchQuery

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 example, to perform a search for mail items in all existing Exchange mailboxes, we can use the following command syntax:

Get-Mailbox -ResultSize Unlimited | Search-Mailbox -SearchQuery

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

Get-Mailbox -Filter '(RecipientTypeDetails -eq "UserMailbox") | Search-Mailbox -SearchQuery

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

Get-Mailbox -Filter '(RecipientTypeDetails -eq "SharedMailbox") | Search-Mailbox -SearchQuery

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

Get-Mailbox -Filter '(RecipientTypeDetails -eq "RoomMailBox") | Search-Mailbox -SearchQuery

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.

Get-DistributionGroupMember <"Distribution Group name"> | Search-Mailbox -SearchQuery

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.

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:

Search-Mailbox <Source Mailbox> -SearchQuery "Kind: meetings"

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

Search-Mailbox <Source Mailbox> -SearchQuery "Kind: contacts"

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

In case 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-Mailbox <Source Mailbox> -SearchQuery from:"<E-mail address>"

Search for mail items, sent to a specific recipient:

Search-Mailbox <Source Mailbox> -SearchQuery to:"<E-mail address>"

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-Mailbox <Source Mailbox> -SearchQuery sent:mm/dd/yyyy

Search for mail items sent on a specific date range:

Search-Mailbox <Source Mailbox> -SearchQuery {sent:mm/dd/yyyy..mm/dd/yyyy}

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-Mailbox <Source Mailbox> -SearchQuery attachment:"<Attachment file name>"

Search for ANY mail items that, include an attachment:

Search-Mailbox <Source Mailbox> -SearchQuery {HasAttachment -eq $true}

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.

Search-Mailbox <Source Mailbox> -SearchQuery ‘Subject:"<Text String>"'

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

Search-Mailbox <Source Mailbox> -SearchQuery Body:"<Text String>"'

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 the 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’” a 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 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 were 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:

Search-Mailbox <Source Mailbox> -TargetMailbox <Target mailbox> -TargetFolder <Target Folder>

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.

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

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 that theoretically, an Exchange user can have an 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 relates to the source mailbox “space.”

Search-Mailbox cmdlet defines the Exchange mailbox “space.”

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

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:

Search-Mailbox <Source Mailbox> -SearchDumpsterOnly

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:

Search-Mailbox <Source Mailbox> -SearchDumpster:$false

In case 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 <Source Mailbox> -DoNotIncludeArchive

Search-Mailbox cmdlet and required permissions

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

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

New-ManagementRoleAssignment -Role "Mailbox Import Export" -User "<user name or alias>"

New-ManagementRoleAssignment -Role "Mailbox Search" -User "<user name or alias>"

Search-Mailbox cmdlet and limitation

The Search-Mailbox cmdlet has two limitations that we should know about.

1. Maximum “source mailboxes.
The Search-Mailbox cmdlet can perform multiple mailbox searches for a maximum of 10,000 mailboxes.

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.