Message Trace Report 1.0.0

Download MessageTraceReport-1.0.0.zip: only the files needed to run (configuration with empty tenant values, SQLite bundled), the HTML guide included. PowerShell 7.4+, Microsoft Graph v1.0, no module needed with a certificate.

First version, replacing Invoke-MessageTraceGraph.ps1.

Highlights

• Four modes: Trace (default — collects only what the local database lacks, then writes the report), Collect (scheduled, whole tenant or a scope, history beyond the 90 days of Graph), Report (database only, any address pattern) and Status.
• Query planner built on the real API behaviour: Graph keeps one value per property in $filter and silently ignores or. One query per address of the shorter list (senders AND recipients), per address (OR); the full filter is applied on the database, so the report is exact. *@domain, subject, status, message ID, source and destination IP.
• Quota-aware: one rolling budget shared by the workers (90 requests / 5 minutes by default), Retry-After honoured, the requests of the last window remembered by the next run, live progress line.
• Restartable: every page stored in SQLite as it arrives; Ctrl+C keeps what was received, the next run collects only the rest; recent hours read again to catch status changes.
• Reports: Messages, Deliveries, Senders, Recipients CSV (Excel-safe, split above 1,000,000 rows), optional JSON with the Graph property names, self-contained HTML report (tiles, status, timeline, top 10, search and filters for 200,000 messages, recipients and route of each message with -IncludeDetails).
• Authentication: certificate (client assertion built in), client secret from an environment variable, or interactive sign-in; tenant and permission checked before the first request.
• Parameter names of Invoke-MessageTraceGraph.ps1 kept as aliases (-StartDate, -Senders, -RecipientsCsv …).

Measured in a lab tenant (same filter, same period)

	Original script	Message Trace Report
1 sender AND 3 recipients, 7 days	31.8 s — 1 recipient of 3	8.5 s — 3 recipients
20 senders, 7 days (558,945 deliveries)	17 min — 8,416 rows lost	6 min 22 s — every row
The same, run again	17 min	27 s

Requirements

Microsoft Graph application permission ExchangeMessageTrace.Read.All with admin consent, and the service principal of the Microsoft application 8bd644d1-64a1-4d4b-ae52-2e0cbf64e373 in the tenant — see the guide, chapter 7.

See CHANGELOG.md and the administrator guide.