This content is part of the Essential Guide: The essential admin's guide to Office 365 PowerShell

How to use the Search-Mailbox cmdlet with Exchange

Administrators can find items in Exchange mailboxes using the Search-Mailbox cmdlet. Here's how to use it to its fullest potential, with an example to follow.

There comes a time in a messaging administrator's life when she needs to search a user's mailbox.

I didn't like to snoop around in employees' mailboxes as an Exchange administrator, but it is necessary in certain scenarios. You might need to access user mailboxes to assist in a regulatory audit, find a message that was sent to lots of users that contains malware or perhaps help an employee find a missing email message.

If your mailboxes are in Office 365, PowerShell makes it easy to search one or more users' mailboxes based on different criteria. To find subjects, phrases or files within Exchange, Search-Mailbox simplifies and automates the process.

Prerequisites for PowerShell

With PowerShell, the Search-Mailbox cmdlet can search for specific criteria across many user mailboxes and send the matching email messages to another mailbox.

To connect your Exchange Online subscription with PowerShell, refer to these instructions from Microsoft. Enable full access to every user mailbox you'd like to search, via either the Office 365 admin center or using the PowerShell script snippet in Listing 1. You must have Exchange admin credentials to do this.

Listing 1. This PowerShell script enables access to an end-user mailbox.

Get-Mailbox -ResultSize unlimited -Filter {(RecipientTypeDetails -eq 'UserMailbox')} | Add-MailboxPermission -User <MyUserAccount> -AccessRights FullAccess -InheritanceType all

Your account must have the Discovery Management admin role. Without it, the Search-Mailbox cmdlet, which we'll use to search mailboxes, will not be available.

How to execute mailbox searches in Exchange

To create searches, use the Search-Mailbox cmdlet. With PowerShell, the Search-Mailbox cmdlet can search for specific criteria across many user mailboxes and send the matching email messages to another mailbox. The simplest way to gather these email copies is in some kind of administrator mailbox. Set a mailbox aside for this purpose ahead of time.

To perform a simple search, you will need to specify, at a minimum, four parameters:

  • Mailbox(es) to search;
  • The search query to use;
  • The target mailbox to which you'll copy matching items; and
  • The target mailbox folder where you'll place the matching items.

The SearchQuery parameter will give you the power to find just about anything. To use this parameter, construct a query in a specific format called Keyword Query Language (KQL). I won't get into any advanced queries, but if you have the patience, you can design a search query to find just about anything.

The difference between Search-Mailbox and New-MailboxSearch

Search-Mailbox and its newer counterpart, New-MailboxSearch are powerful cmdlets. New-MailboxSearch suits large mailbox count operations that number more than 10,000. Search-Mailbox can be used for smaller operations. New-MailboxSearch has reporting built-in, while Search-Mailbox does not. However, more administrators are familiar with Search-Mailbox for Exchange, and it can be easier to use than New-MailboxSearch.

The hardest part is constructing the right KQL query. For a full breakdown, visit the Technet page or simply refer to the built-in help for this cmdlet by typing Get-Help Search-Mailbox –Detailed into your PowerShell console.

Example query search

In this example, I want to search all of my Office 365 tenants' mailboxes for a specific subject. Through my research, I've found that I can search for a subject with KQL by using the string Subject=<Subject>. I have a target mailbox called DiscoverySearch where I will place the matching items and I will have Search-Mailbox create a folder called SearchResults (Listing 2).

Listing 2. The text shows a PowerShell script to search all mailboxes for a given subject and copy matching results to a SearchResults folder.

Get-Mailbox | Search-Mailbox -SearchQuery "Subject:Some Subject" -TargetMailbox "DiscoverySearch" -TargetFolder "SearchResults"

I'm using Get-Mailbox to enumerate all of the mailboxes in my Office 365 tenant. I pass that result directly to Search-Mailbox. This tactic avoids specifying the –Identity parameter to Search-Mailbox, giving the administrator an easier way to define which mailboxes to search if the scope does not include every mailbox.

Next Steps

Become an Exchange PowerShell master

Understanding Exchange 2013's compliance features

Learn how to clear audit logs

Dig Deeper on Office 365 and Microsoft SaaS setup and management