- Azure Bicep: Getting started guide - Fri, Nov 19 2021
- Running PowerShell scripts remotely on Azure virtual machines - Fri, Oct 29 2021
- Migrate Skype for Business to Microsoft Teams with Meeting Migration Service - Tue, Dec 29 2020
The first command we are going to focus on is Search-Mailbox. This command is available going back to at least Exchange Server 2010, and its power derives from the SearchQuery parameter. This parameter allows complex search queries using Keyword Query Language (KQL). KQL allows searching for attachment names, specific senders, or even a date range. Despite the available search query options, the Search-Mailbox command has a few limitations to be aware of:
- It can only search a maximum of 10,000 mailboxes at a time.
- If using a search query, it will return only a maximum of 10,000 items in the search results.
- If the mailbox has an archive attached, it will search both the mailbox and the archive (unless you've excluded the archive).
- You must assign the Mailbox Search management role to the user performing the searches. This allows using the Search-Mailbox command in PowerShell. This role links up to the Discovery Management admin role.
Let's look at a few examples searching Jane Johnson's mailbox and storing the search results in the Administrator's mailbox in the SearchResults folder:
# Search for emails from Kevin McDonald: Search-Mailbox -Identity 'Jane Johnson' -SearchQuery From:'Kevin McDonald' TargetMailbox Administrator -TargetFolder SearchResults -LogOnly -LogLevel Full # Search for email with a subject containing the word 'dogmatic': Search-Mailbox -Identity 'Jane Johnson' -SearchQuery subject:'dogmatic' -TargetMailbox Administrator -TargetFolder SearchResults -LogOnly -LogLevel Full # Search for emails with a .txt attachment: Search-Mailbox -Identity 'Jane Johnson' -SearchQuery attachment:.txt -TargetMailbox Administrator -TargetFolder SearchResults -LogOnly -LogLevel Full
Specifying the TargetMailbox and TargetFolder parameters will send the search results to that mailbox and folder. If you want to copy the contents of a search to the mailbox, remove the LogOnly parameter and rerun the search. This will copy the search results to the specified mailbox folder grouped by the mailbox name, the mailbox where it found it (primary or archive), and the mailbox folder. Here is an example of the results in the target mailbox and folder:
The search query also allows searching with multiple parameters, such as the sender and specific attachment. This command will search Jane Johnson's mailbox for emails from Jennifer Lunn with .txt attachments:
Search-Mailbox -Identity 'Jane Johnson' -SearchQuery 'From:"Jennifer Lunn" and attachment:.txt' -TargetMailbox Administrator -TargetFolder SearchResults -LogLevel Full
Notice in the above command the search query has multiple sets of quotation marks in it. The recommended approach is to enclose the entire search query in single quotes and any search properties in double quotes.
Finally, after searching, copying, and verifying the results, remove the logging and target parameters and add the DeleteContent parameter to remove the emails from the target mailbox:
Search-Mailbox -Identity 'Jane Johnson' -SearchQuery 'From:"Jennifer Lunn" and attachment:.txt' -DeleteContent
As outlined earlier, Search-Mailbox has several limitations. To improve on these commands, Exchange Server 2016 and Exchange Online introduced two new commands: New-ComplianceSearch and New-ComplianceSearchAction. These new commands can search an unlimited number of mailboxes in a single search.
The removal of the 10,000-mailbox limitation lets large organizations perform search and delete operations across the entire infrastructure as needed. As with the other search commands, the administrator will need the Mailbox Search management role, and this can only remove a maximum of 10 items per mailbox at once. This is because these commands should be a part of an incident response playbook and should not serve to clean up large amounts of emails from user mailboxes.
The first step in using these new commands is to create and to run a compliance search to find the message to delete. The New-ComplianceSearch command uses the ContentMatchQuery parameter to search for specific emails matching the criteria. The search query also uses KQL-formatted commands to find matching emails. The ExchangeLocation specifies a mailbox or distribution group members to search, or use All to search every mailbox. Let's take our three examples from earlier and convert them to the new command:
New-ComplianceSearch -Name 'JJohnson Ex1' -ExchangeLocation 'Jan Johnson' ‑ContentMatchQuery from:'Kevin McDonald' New-ComplianceSearch -Name 'JJohnson Ex2' -ExchangeLocation 'Jan Johnson' ‑ContentMatchQuery from:subject:'dogmatic' New-ComplianceSearch -Name 'JJohnson Ex3' -ExchangeLocation 'Jan Johnson' ‑ContentMatchQuery attachment:.txt
Notice we do not have an option for copying content to a mailbox or viewing the results. This command only creates search criteria for the targeted mailboxes. To execute the search and remove the content for the 'JJohnson Ex1' search, run the following command:
New-ComplianceSearchAction -SearchName 'JJohnson Ex1' -Purge -PurgeType SoftDelete
SoftDelete is the only option available for the PurgeType, meaning it will move the emails to the Recover Deleted Items folder of the user's mailbox. Remember, the purge action will only remove 10 items from a mailbox at a time. When I ran the above search for emails from Kevin McDonald, it found 18 matches. When I ran the purge command, it only removed 10, leaving the remaining 8 still in the Inbox.
Subscribe to 4sysops newsletter!
This means we should restrict the compliance searches to cases where we need to remove fewer than 10 emails per mailbox. Determining which command to use will depend upon how many mailboxes we need to search, how many emails in each mailbox we need to remove, and whether we need a copy of the emails before deleting.