Message trace in Exchange Online via Microsoft Graph: wat er verandert

Wie wil weten wat er met een e-mail is gebeurd, gebruikt in Exchange Online de message trace. Tot nu toe was de programmatische route daarvoor de Reporting Web Service, een REST-eindpunt dat al jaren meegaat. Op 22 januari 2026 kondigde het Exchange-team aan dat message trace via de Microsoft Graph API in public preview ging; op 6 februari 2026 werd daar een update aan toegevoegd: de functie is algemeen beschikbaar in de Multi-Tenant-omgeving (WW). Tegelijk staat de klok voor de oude route te lopen.

Dit artikel zet op een rij wat de nieuwe API biedt, welke voorbereiding nodig is en wat de aangekondigde tijdlijn betekent voor bestaande scripts en koppelingen.

Wat message trace doet

Een message trace volgt een bericht door de Exchange Online-organisatie: is het afgeleverd, staat het nog in de wachtrij, is het geweigerd, in quarantaine gezet of als spam gefilterd? Beheerders gebruiken dit dagelijks bij meldingen dat een e-mail niet is aangekomen en bij het onderzoeken van afleverproblemen met externe domeinen.

In het Exchange-beheercentrum is dit een scherm; in scripts en monitoringtools was het tot nu toe de Reporting Web Service of de bijbehorende PowerShell-cmdlets. De nieuwe Graph-resource brengt dezelfde functionaliteit naar het API-platform dat voor de rest van Microsoft 365 al de standaard is.

De resource exchangeMessageTrace

De API leeft onder de beta-versie van Microsoft Graph als resourcetype exchangeMessageTrace. Twee methoden zijn beschikbaar:

Dat is dezelfde tweedeling die beheerders kennen van de cmdlets: eerst zoeken, dan de details van één bericht opvragen.

De resource heeft de volgende eigenschappen:

• id – unieke identificatie van de trace
• messageId – de Message-ID-header van het bericht
• receivedDateTime – het moment (UTC) waarop Exchange Online het bericht ontving; filterbaar met ge en le
• senderAddress en recipientAddress – SMTP-adressen van afzender en geadresseerde
• subject – de onderwerpregel; filterbaar met contains, startsWith en endsWith
• status – de afleverstatus: gettingStatus, pending, failed, delivered, expanded, quarantined of filteredAsSpam
• size – grootte in bytes
• fromIP en toIP – bron- en bestemmings-IP; voor inkomende mail is toIP leeg

De filtermogelijkheden op receivedDateTime en subject zijn relevant voor wie de beheerderservaring wil nabouwen: een periode afbakenen en op een deel van het onderwerp zoeken is precies wat in de praktijk het meest gebeurt.

Voorwaarde: een service principal in de tenant

Anders dan bij de meeste Graph-resources is er een extra stap nodig voordat de API werkt. In de tenant moet een service principal worden aangemaakt voor de Microsoft-toepassing met application (client) ID 8bd644d1-64a1-4d4b-ae52-2e0cbf64e373. Dat maakt een lokale representatie van die toepassing in de directory en maakt authenticatie en autorisatie voor deze API's mogelijk. De blogpost verwijst hiervoor naar de uitfasering van authenticatie zonder service principal.

De documentatie beschrijft de stap met Microsoft Graph PowerShell:

Connect-MgGraph -Scopes "Application.ReadWrite.All"
New-MgServicePrincipal -AppId 8bd644d1-64a1-4d4b-ae52-2e0cbf64e373

Zonder deze stap geven de methoden List message traces en Get details by recipient geen resultaat. Wie de API in een tenant wil gaan gebruiken, plant deze provisioning dus vóór de eerste test in.

Limieten

De aankondiging noemt expliciete grenzen, die ook gelden voor de PowerShell-cmdlets Get-MessageTraceV2 en Get-MessageTraceDetailV2:

• maximaal 100 message-trace-aanvragen per tenant binnen een lopend venster van 5 minuten;
• maximaal 5.000 resultaten per aanvraag, dus tot 500.000 resultaten per venster van 5 minuten;
• gespreid over een dag tot 144 miljoen resultaten.

Voor het gewone beheerwerk zijn dit ruime marges. Ze doen er wél toe bij tooling die periodiek de volledige mailstroom ophaalt, bijvoorbeeld voor archivering of een SIEM. Zulke koppelingen moeten de aanvragen spreiden en de resultaten pagineren in plaats van in één keer alles op te vragen.

Tijdlijn voor de Reporting Web Service

De nieuwe API vervangt de bestaande message-trace-ondersteuning via de Reporting Web Service. De aankondiging geeft voor de Multi-Tenant-omgeving (WW) twee data:

Andere cloudomgevingen krijgen volgens de post een eigen tijdlijn; ook de beschikbaarheid van de Graph-variant volgt daar later. Nieuw aangemaakte organisaties hebben volgens de post standaard al geen toegang meer tot de Reporting Web Service.

Voor bestaande omgevingen betekent dit een inventarisatie: welke scripts, monitoringtools of rapportages praten met de Reporting Web Service voor message trace? Denk aan geplande taken die afleverfouten rapporteren, helpdesktools die een trace opvragen en koppelingen met ticketsystemen. Elk daarvan heeft vóór april een vervanging nodig, via de Graph-API of via de V2-cmdlets in Exchange Online PowerShell.

Wat dit betekent voor scripts

Voor een beheerder die alleen de cmdlets gebruikt, verandert er functioneel weinig: Get-MessageTraceV2 en Get-MessageTraceDetailV2 bieden dezelfde tweedeling als de Graph-methoden en vallen onder dezelfde quota. Voor wie een eigen toepassing bouwt, is de Graph-route de aangewezen weg. Daarbij hoort de eerdere kanttekening: de resource staat onder beta, en de gebruikelijke praktijk is om beta-afhankelijkheden in productiecode te isoleren zodat een wijziging in de API niet de hele toepassing raakt.

De belangrijkste conclusie voor februari 2026 is praktisch: de nieuwe API is beschikbaar, de service principal is een harde voorwaarde, en de oude route heeft in de WW-omgeving een begindatum voor uitfasering. Alles wat nu nog op de Reporting Web Service leunt, verdient een plek op de planning voor de komende weken.

Bronnen

• Message Trace support using Graph API is now in Public Preview – Exchange Team Blog, 22 januari 2026, bijgewerkt 6 februari 2026
• exchangeMessageTrace resource type – Microsoft Graph beta – Microsoft Learn