Table of Contents
Use a Historical Message Trace to Find Inbound Email Delivered to Shared Mailboxes
Updated 24-Oct-2023
A question in the Facebook group for Office 365 Technical Discussions (no YouTube videos or marketing posts accepted) asked how to check shared mailboxes for email received from external senders over the past sixty days. The check should look for email received from a specific domain and report details of those messages.
Given the number of shared mailboxes that might be used in a tenant and the volume of email that these mailboxes might receive, running a manual check is not feasible. You would have to sign into each mailbox and review their content. This is a tiresome process that wouldn’t detect messages received from the specific domain that users subsequently deleted (or messages removed by a retention policy).
Exchange Historical Message Traces
Exchange Online historical message traces can go back a maximum of 90 days, so they can be used to search the data logged by Exchange Online when it delivers messages to mailboxes. A single historical message trace can cover up to 100 sender or recipient addresses. If a tenant wants to check email related to a larger number of addresses, they can split the check across multiple searches and combine the results.
It all sounds so easy to script. Run the Start-HistoricalSearch cmdlet to submit the message trace. Check the output. Find and report problem messages. Easy. But as is so often the case, some complexity lurks under the surface.
Submit a Historical Message Trace and Wait
The PowerShell code to automate the check must be split into two scripts. The first creates and submits the historical message trace job. The second analyzes the results of the trace. The two cannot be connected because Exchange Online runs historical message trace jobs in the background as service resources allow. If you’re lucky, a message trace might complete in less than twenty minutes. More often, it will take an hour or so.
Here’s the code I used to submit the job. It finds the set of shared mailboxes, sets the search period, and creates the parameters for the Start-HistoricalSearch cmdlet to process. As noted above, a historical message trace can process up to 100 mailboxes, so a check is there to make sure that we don’t attempt to schedule a job for more than this number of mailboxes.
# Find all shared mailboxes
[array]$SharedMailboxes = Get-ExoMailbox -RecipientTypeDetails SharedMailbox
If ($SharedMailboxes.Count -gt 100) {
Write-Host ("Too many shared mailboxes found - we can't do a message trace for {0} mailboxes" -f $SharedMailboxes.Count) ; break
}
[array]$RecipientAddresses = $SharedMailboxes.PrimarySmtpAddress
# Submit historical search (maximum of 250 per day)
Start-HistoricalSearch -RecipientAddress $RecipientAddresses -StartDate (Get-Date).AddDays(-60) -EndDate (Get-Date) -ReportType MessageTrace -ReportTitle ("Report Shared Mailbox {0}" -f (Get-Date))
Although you could code a loop to use the Get-HistoricalSearch cmdlet to check the progress of the search job and resume when the job completes, a further complication is that Exchange Online stores the message trace results in Azure storage. There’s no way for PowerShell to download the data for processing. Instead, an Exchange administrator goes to the Mail flow section of the Exchange admin center to view the status of historical message trace jobs and download the results if the job to scan for shared mailbox traffic is complete (Figure 1).
Processing Historical Message Trace Results
Exchange Online downloads the message trace results using a URL like:
The result is a CSV file in the Downloads folder with a name with a “MTSummary_Report” prefix followed by the historical message trace name and an identifier. For instance:
MTSummary_Report Shared Mailbox Scan 12062022 184532_044439ab-614e-4ec6-b4d9-a095c92befbe
Occasionally, the data generated by Exchange Online doesn’t import properly into PowerShell using the Import-CSV cmdlet. To make sure that everything works, I open the downloaded file with Excel and save it to a known location, like c:\temp\MessageTraceResults.csv. The save seems to cure any lingering data formatting problems.
We can now process the data by first searching the records to find if any originated from the domain of interest. For the purpose of this exercise, I’ll search for messages originating from Practical365.com:
[array]$MessageData = Import-CSV c:\temp\MessageTraceResults.CSV
[array]$ProblemItems = $MessageData | Where-Object {$_.Sender_Address -like "*practical365.com"}
If (!($ProblemItems)) { Write-Host "No email found from Practical365.com - exiting" ; break }
Creating a report from the discovered items is simple:
$ProblemInfo = [System.Collections.Generic.List[Object]]::new()
ForEach ($Item in $ProblemItems) {
$DataLine = [PSCustomObject] @{
Timestamp = Get-Date($Item.origin_timestamp_utc) -format g
Sender = $Item.Sender_Address
Subject = $Item.Message_Subject
Recipient = $Item.Recipient_Status.Split("##")[0] }
$ProblemInfo.Add($DataLine)
} # End ForEach Item
Figure 2 shows the report of the messages received from Practical365.com.
Getting the Job Done
Some organizations extract and move message trace data to external repositories like Splunk to make it easier to perform this kind of tracing. An external repository usually allows for long-term storage and is more flexible in terms of its search capabilities. However, the basic tools built into Exchange Online can do the job, even if the PowerShell processing is split into two tasks. It would be nice if Microsoft allowed tenants to download the message trace data with PowerShell to avoid the messing around with CSV files, but that’s just a small complaint.
Learn how to exploit the data available to Microsoft 365 tenant administrators through the Office 365 for IT Pros eBook. We love figuring out how things work.