Update 5/6/2025: We added information about new cmdlet throttling limit.
Today, we are excited to announce that the Public Preview of the new Message Trace in the Exchange admin center (EAC) in Exchange Online will begin rolling out mid-December and is expected to be completed by the end of December 2024. Admins will soon be able to access the new Message Trace and its capabilities by default when navigating to the Exchange admin center > Mail flow > Message Trace.
As illustrated in the image below, the new Message Trace will be toggled “on” by default once the change has been deployed to your tenant. If you wish to disable the preview, you can do so by toggling this setting to “off.”
Key UI functionality changes
- Extended Query Range: You can now query up to 90 days of historical data for near real-time queries. However, please note that you can only query 10 days’ worth of data at a time. Please note that you will initially only have 30 days of historical data for near real-time query, and this will build over time to 90 days of historical data.
- Subject Filter: The subject filter for Message Trace queries is now available, supporting "starts with", "ends with", and "contains" functions. This filter also supports special characters.
- Delivery Status Filter: The delivery status filter will now support searches for "Quarantined", "Filtered as spam", and "Getting status" statuses.
Additional UI updates based on feedback
- Customizable Columns: For your search results, we’ve introduced customizable columns and added additional column options that you can select from. Please refer to the image below for the new columns that have been added.
- Persistent Column Widths: You will be able to customize your column-widths, and these changes will be sticky per logged-on admin account, so they will not have to be reset every time you run a new message trace query. This change is currently in progress and will be made available in early February.
- Wider Flyout Option: An option for a wider flyout for the Message Trace detail is now available.
- Time Zone Consistency: Message Trace will now default to the time zone set in the Exchange account settings of the logged-on admin.
Key cmdlet changes from Get-MessageTrace
To utilize the new Message Trace functionality via the new PowerShell cmdlet Get-MessageTraceV2 please ensure you are using version 3.7.0 or later of the Exchange Online PowerShell V3 module.
-
Extended Query Range: Ability to query up to 90 days of historical data. However, please note that you will only be able to query 10 days’ worth of data per query. Please note that you will initially only have 30 days of historical data for near real-time query, and this will build over time to 90 days of historical data.
-
Subject Parameter: The addition of a subject parameter allowing for more specific Message Trace queries.
-
No Page number or Page size parameter: There will not be pagination support in the new Message Trace cmdlet.
- Result size parameter: The new Message Trace will support a default value of 1000 results and a maximum of 5000 results (set via the -ResultSize parameter). This change is to ensure fair use of our resources, as pagination can create performance issues for our system.
- StartingRecipientAddress parameter: This parameter’s main use is to assist in pulling subsequent data while minimizing duplication.
Since pagination will no longer be supported, you can utilize the EndTime parameter with the "Received" time of the last record of the query results and fill in the StartingRecipientAddresss parameter with RecipientAddress of the last record of the previous result. See the example below for more details.
Example of differences between V1 and V2:
For the sample data above, you can pull the first 10 records by either query:
Old Message Trace
Get-MessageTrace -StartDate '2024-11-01T00:00:00Z' -EndDate '2024-11-01T00:10:00Z' -Page 1 -PageSize 10
New Message Trace
Get-MessageTraceV2 -StartDate '2024-11-01T00:00:00Z' -EndDate '2024-11-01T00:10:00Z' -ResultSize 10
To pull the next subsequent records, you could use either of the following queries. In the V2 example below, we are using the StartingRecipientAddress of last recipient (r_1_010@contoso) from the previous results.
Old Message Trace
Get-MessageTrace -StartDate '2024-11-01T00:00:00Z' -EndDate '2024-11-01T00:10:00Z' -Page 2 -PageSize 10
New Message Trace
Get-MessageTraceV2 -StartDate '2024-11-01T00:00:00Z' -EndDate '2024-11-01T00:10:00Z' -ResultSize 10 -StartingRecipientAddress r_1_010@contoso.com
- Throttling Limits: To reduce the risk of misuse and abuse of Exchange Online resources, ensure services availability for all users, and provide a predictable experience for our customers, we will implement a rate-based throttling limit based on the number of requests in a time period. For a tenant, a maximum of 100 query requests will be accepted within a 5-minute running window. Throttling is automatically not applied if the request rate is lower than 100 requests in the past 5 minutes. If your tenant has automation set up to query more frequently than the throttling threshold, please update your automation to fit below the throttling limit.
|
Cmdlet | Tenant level limit |
|
Get-MesesageTraceV2 |
100 requests per 5 min |
|
Get-MessageTraceDetailV2 |
100 requests per 5 min |
Best practices
To improve query performance, specify as many and as precise filters as possible.
We highly recommend that admins narrow the gap between StartDate and EndDate whenever possible. It is also advisable to set additional parameters, such as SenderAddress, when the sender is known.
Use MessageTraceId when applicable for PowerShell queries. Note that this is required when querying data for messages sent to over 1,000 recipients. This is also supported in EAC now.
Set the MessageTraceId (also known as NetworkMsgId in the message tracking log) when investigating a specific message or when a message is sent to many recipients (e.g., over 1,000). This is required to obtain complete results. When used together with StartingRecipientAddress, you can retrieve the full dataset in multiple rounds. See the FAQ section for more details on StartingRecipientAddress.
Frequently asked questions
How can we tell if partial results are displayed?
For Exchange Admin Center (EAC) users, scroll down to get more results until the data is complete. Users don't have to take any additional action, and V2 will load it automatically as user scrolls down to get additional results. For Exchange Online PowerShell cmdlet users, we are working on providing a hint in the output for the next query if the data is partial (expected within next few weeks). For now, users can utilize the sample script below to gather results continuously.
Sample script:
$mt = Get-MessageTraceV2 -<filters>
$nextRound = Get-MessageTraceV2 -<filters> -EndDate $mt[-1].Received.ToString(“O”)
How could pagination from V1 be achieved in V2?
Pagination is deprecated in V2 to ensure fair use of resources and query performance for all users. Instead, you can get results round by round. The results are ordered by Received in descending order first, then RecipientAddress in ascending order (case-insensitive). To get the next round of results, update the EndDate parameter to the Received value of the last data from the current round. Refer to the sample scripts in the previous section.
When and how could we use the parameter: StartingRecipientAddress?
The StartingRecipientAddress parameter is used to get the next round of data. StartingRecipientAddress,together with Received, can get the results round by round to get the complete results. In the next round, data that shares the same Received as the last result in the current round but has RecipientAddress that is alphabetically larger than the StartingRecipientAddress(case-insensitive), or older than the last result in the current round, will be output.
Sample script:
$mt = Get-MessageTraceV2 -<filters>
$nextRound = Get-MessageTraceV2 -<filters> -EndDate $mt[-1].Received.ToString(“O”) -StartingRecipientAddress $mt[-1].RecipientAddress
Known differences
- Message trace V1 normalizes all recipients to lowercase, while V2 keeps them the same as in Message Tracking Logs.
- When displaying the results, V2 will order by Received in descending order first, then RecipientAddress in ascending order(case-insensitive).
- V2 retrieves the most up-to-date email size from the email system, providing a more accurate reflection of the current status, whereas V1 returns the earliest recorded size.
- For messages with over 1000 recipients, admins must include the MessageTraceId in both the EAC and PowerShell cmdlet queries to avoid partial results.
- For quarantine scenarios, V2 will display the latest status while V1 displayed the original status. So if the email is quarantined initially and then released by the administrator later, Message Trace v2 will show the latest status which is delivered to Mailbox.
We plan to eventually deprecate the old message trace UI and PowerShell command; we will share more details when the feature reaches General Availability.
Microsoft 365 Messaging Team
