Why · How it works · Reports · Get started · User guide · Developer guide
Tip
Download the latest release. Open the latest release and download MessageTraceReport-1.1.1.zip under Assets (its SHA-256 is in the release notes). That ZIP is the signed tool. Do not use the Source code archives or the green Code button: they are a copy of the repository, not the release package.
Important
Files downloaded from the Internet may be blocked by Windows and fail to run. Before using this tool, unblock every file in the folder where you extracted it:
Get-ChildItem "C:\Tools\MessageTraceReport-1.1.1" -Recurse -File -Force | Unblock-FileReplace the example path with the folder where you extracted the release ZIP.
Message Trace Report answers two everyday questions about Exchange Online mail: did this message arrive, and who received it? and why was it not delivered? It reads the message trace of Microsoft 365 through the Microsoft Graph API, which has strict limits (about 100 requests per 5 minutes for the whole tenant, 10-day windows, 90 days of history). The tool works within these limits for you, keeps everything it receives in a local SQLite database (a single file on your disk, nothing to install) and never asks Microsoft twice for what it already holds.
- You give a filter (senders, recipients, a domain such as
*@fabrikam.com, a subject, a status, a message ID or an IP address). The tool works out what Microsoft must be asked and what it can answer from its own database, so the report is exact. - It stays inside the Microsoft limits: it spaces its requests, waits when Microsoft asks it to and retries after a network error.
- It is safe to interrupt: press Ctrl+C or lose the network, and what was received is kept; the next run collects only the rest.
-Mode Collectrun every day keeps the whole tenant beyond the 90 days that Microsoft keeps;-Mode Reportanswers from the database alone, with any address pattern.- Why a message was not delivered: with
-IncludeDetails, each recipient gets a plain-words cause such as Blocked by DLP, Blocked by mail flow rule (ETR), Recipient not found, Mailbox full, Quarantined or Rejected by remote server, with the rule, the status code and its Microsoft Learn page, and the point where the route of a failed recipient left the route of the delivered ones. - Read-only: one permission (
ExchangeMessageTrace.Read.All), certificate sign-in, nothing to install.
Each run writes Messages.csv (one row per message), Deliveries.csv (one row per message and recipient), Routes.csv (one row per step of the routes read), Senders.csv and Recipients.csv (per day), optionally JSON files, and a self-contained HTML report that stays fast with 200,000 messages.
| Item | Requirement |
|---|---|
| PowerShell | PowerShell 7.4 or later (pwsh). Windows PowerShell 5.1 is not enough. |
| Modules | None for certificate or secret sign-in. Interactive sign-in uses Microsoft.Graph.Authentication. |
| Permission | An app registration with the Microsoft Graph permission ExchangeMessageTrace.Read.All and admin consent. |
| Tenant | A service principal of the Microsoft message trace service: a one-time entry that lets Microsoft Graph answer message trace requests for your tenant. The user guide gives the command. |
| SQLite | Bundled in lib\sqlite, nothing to install. |
-
Download
MessageTraceReport-1.1.1.zipfrom the latest release (use this file, not the Source code archives). -
Extract it, for example to
C:\Tools\MessageTraceReport-1.1.1. The ZIP holds one folder,MessageTraceReport-1.1.1. -
Open PowerShell 7. In File Explorer, open the extracted folder, click the address bar, type
pwshand press Enter. Check it:$PSVersionTable.PSVersion Get-ChildItem . -Recurse -File -Force | Unblock-File
You should see a version that starts with 7 (7.4 or later), then no output from the second command. If
pwshis not recognized, install PowerShell 7 first. -
Set up the application once and fill in the configuration, as chapter 2 of the user guide explains, step by step (
docs\MessageTraceReport-UserGuide.htmlin the ZIP; double-click it). -
Run your first trace:
.\Invoke-MessageTraceReport.ps1 -Sender john@contoso.com -Range Last7Days -Open
You should see the plan, a progress line, the list of files written under
reports\, and the HTML report opening in your browser.
More commands, one per question:
.\Invoke-MessageTraceReport.ps1 -Recipient *@fabrikam.com -Status Failed -Range Last7Days -Open
.\Invoke-MessageTraceReport.ps1 -SenderFile C:\Tools\MessageTraceReport-data\vip.csv -Recipient *@gmail.com -Start 2026-09-01 -End 2026-10-01
.\Invoke-MessageTraceReport.ps1 -MessageId '<CAJ1234@mail.contoso.com>' -Range Last10Days -IncludeDetails # why each recipient got it or not
.\Invoke-MessageTraceReport.ps1 -Mode Collect # scheduled task, whole tenant
.\Invoke-MessageTraceReport.ps1 -Mode Report -Range Last30Days -Sender 'sales-*@contoso.com'
.\Invoke-MessageTraceReport.ps1 -Mode StatusComing from Invoke-MessageTraceGraph.ps1? Its parameter names are kept as aliases (-StartDate, -Senders, -RecipientsCsv ...): see the migration table.
| Guide | Content |
|---|---|
| User guide | What you need before the first trace, the one-time setup step by step, then one command per everyday question: a sender, a domain, a list of addresses, a message ID, why a recipient did not get it, the daily collection, a report from the database. How to read the results and what to do when something goes wrong. |
| Developer guide | Everything else: how the Graph API behaves and how the tool plans around it, performance figures, every configuration key, the routes in detail, the scheduled collection, the report columns, exit codes and logs, the migration from the original script, the internals and how to test a change. |
Both guides also exist as a single HTML file with a light and a dark theme, docs\MessageTraceReport-UserGuide.html and docs\MessageTraceReport-Guide.html, in the release ZIP.
git clone https://github.com/Nico77600/MessageTraceReport.git
cd MessageTraceReport
Invoke-Pester -Path .\tests # Pester 5+, in-memory Graph API, no connection to Microsoft 365
.\tests\New-DemoReport.ps1 -Open # a report of fictitious Contoso data, through the real engine
.\tools\New-MtrPackage.ps1 -Unsigned -Zip -Destination C:\Build\MessageTraceReport # unsigned package folder and ZIP for testsThe run-time files are in package\. tools\Build-Documentation.ps1 rebuilds the HTML guides; tools\New-ReadmeImages.ps1 renders the graphics of this page.
MIT. The bundled SQLite components keep their own licenses: see THIRD-PARTY-NOTICES.md.
This Script is a Personal project. It's provided "AS-IS". It's not an official Microsoft product so no support can be expected from Microsoft.
As any scripts you must read carefully the documentation and test it first in a Test environment before any run in Production.



