Wie wil weten wat er met een e-mail is gebeurd, gebruikt in Exchange Online de message trace. De programmatische route daarvoor was tot nu toe 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 volgde een toevoeging aan dezelfde post: de functie is algemeen beschikbaar in de Multi-Tenant-omgeving (WW). Volgens de aankondiging vervangt de Graph-variant de bestaande message-trace-ondersteuning via de Reporting Web Service, en daarvoor is een uitfaseringsdatum genoemd.
Dit artikel zet op een rij wat de nieuwe API biedt, welke voorbereiding in de tenant nodig is, welke limieten gelden 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? De documentatie omschrijft de functie als een middel voor tenantbeheerders om de levenscyclus van een e-mail te volgen, de afleverstatus te bepalen en te zien welke acties erop zijn toegepast.
In het Exchange-beheercentrum is dit een scherm; in scripts en monitoringtools was het tot nu toe de Reporting Web Service. 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, in de API-referentie ondergebracht bij Mail. Twee methoden zijn beschikbaar:
| Methode | HTTP-aanroep | Retourneert |
|---|---|---|
| List message traces | GET /admin/exchange/tracing/messageTraces | verzameling exchangeMessageTrace |
| Get details by recipient | GET /admin/exchange/tracing/messageTraces/{id}/getDetailsByRecipient(recipientAddress='…') | verzameling exchangeMessageTraceDetail |
Dat is dezelfde tweedeling die beheerders kennen uit het beheercentrum: eerst zoeken, dan de gebeurtenissen van één bericht voor één ontvanger opvragen.
De resource heeft de volgende eigenschappen:
id– unieke identificatie van de tracemessageId– de Message-ID-header van het berichtreceivedDateTime– het moment (UTC) waarop Exchange Online het bericht ontving; filterbaar metgeenlesenderAddressenrecipientAddress– SMTP-adressen van afzender en geadresseerdesubject– de onderwerpregel; filterbaar metcontains,startsWithenendsWithstatus– de afleverstatus:gettingStatus,pending,failed,delivered,expanded,quarantined,filteredAsSpamofunknownFutureValuesize– grootte in bytesfromIPentoIP– bron- en bestemmings-IP; voor inkomende mail istoIPleeg
De detailresource exchangeMessageTraceDetail beschrijft één gebeurtenis in de verwerking van het bericht: dateTime (UTC), event (bijvoorbeeld Receive of Deliver), action, description, data, id en messageId.
Beta betekent beta
De documentatie van de resource staat onder /beta en draagt de standaardwaarschuwing dat beta-API's kunnen wijzigen en dat gebruik in productietoepassingen niet wordt ondersteund. De blogpost meldt tegelijk dat de functie in de WW-omgeving algemeen beschikbaar is. Van een v1.0-versie is in de documentatie op dit moment geen sprake.
Permissie en authenticatie
Beide methoden vragen de Graph-permissie ExchangeMessageTrace.Read.All, zowel als delegated permissie (werk- of schoolaccount) als application-permissie. Persoonlijke Microsoft-accounts worden niet ondersteund. De onboarding guide werkt met app-only-authenticatie: een app-registratie met een client secret, een certificaat of een federated identity credential, waarna de application-permissie wordt toegekend en admin consent wordt gegeven. Voor productie beveelt Microsoft een certificaat van een vertrouwde certificaatautoriteit aan boven een secret.
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 multitenant-toepassing in de directory en maakt authenticatie en autorisatie voor deze API's mogelijk. De blogpost koppelt deze stap aan de uitfasering van authenticatie zonder service principal in het Microsoft identity platform.
De documentatie beschrijft de stap met Microsoft Graph PowerShell:
Connect-MgGraph -Scopes "Application.ReadWrite.All"
New-MgServicePrincipal -AppId 8bd644d1-64a1-4d4b-ae52-2e0cbf64e373
Hetzelfde kan via Graph Explorer met een POST naar https://graph.microsoft.com/v1.0/servicePrincipals en de body { "appId": "8bd644d1-64a1-4d4b-ae52-2e0cbf64e373" }. Na het aanmaken kan de provisioning volgens de onboarding guide enkele uren duren. In die periode geeft de API 401 (Unauthorized) terug met de melding dat de service principal voor dit app-ID niet is gevonden.
Zoeken, filteren en pagineren
De onboarding guide en de methodedocumentatie geven de werkgrenzen van een query:
- Zonder parameters retourneert de API de afgelopen 48 uur.
- Een periode wordt afgebakend met beide grenzen:
$filter=receivedDateTime ge {start} and receivedDateTime le {eind}, in ISO 8601 (YYYY-MM-DDThh:mm:ssZ). Eén query mag maximaal 10 dagen omvatten; de startdatum ligt hoogstens 90 dagen terug. $filterwerkt opid,messageId,receivedDateTime,recipientAddress,senderAddress,status,subjectentoIP.- De standaardpagina is 1.000 objecten;
$topaccepteert waarden van 1 tot 5.000. Als er meer resultaten zijn, bevat het antwoord@odata.nextLink; die volledige URL, inclusief$skiptoken, is de volgende aanvraag.
Een eenvoudige aanroep ziet er zo uit:
GET https://graph.microsoft.com/beta/admin/exchange/tracing/messageTraces?$filter=receivedDateTime ge 2026-02-01T00:00:00Z and receivedDateTime le 2026-02-03T00:00:00Z and senderAddress eq 'noreply@contoso.com'&$top=500
De details van één bericht volgen daarna met getDetailsByRecipient op het id uit het zoekresultaat.
Limieten
De aankondiging noemt expliciete grenzen. Alle aanroepen van message trace en message trace detail delen één quotum: per tenant worden maximaal 100 aanvragen geaccepteerd binnen een lopend venster van 5 minuten. Onder die grens wordt niet gethrottled. Aanvraag en resultaatomvang zijn twee verschillende zaken: één aanvraag levert tot 5.000 resultaten, dus tot 500.000 resultaten per venster van 5 minuten en, verspreid over een dag, tot 144 miljoen resultaten.
Dezelfde tenantlimiet van 100 aanvragen per 5 minuten geldt volgens de post voor de Exchange Online PowerShell-cmdlets Get-MessageTraceV2 en Get-MessageTraceDetailV2.
Voor het gewone beheerwerk zijn dit ruime marges. Ze doen ertoe bij tooling die periodiek de volledige mailstroom ophaalt, bijvoorbeeld voor archivering of een SIEM: daar bepalen het aantal aanvragen per 5 minuten en de paginagrootte samen hoeveel er per dag door de API past.
Tijdlijn voor de Reporting Web Service
De aankondiging geeft voor de Multi-Tenant-omgeving (WW) twee data:
| Datum | Gebeurtenis volgens de aankondiging |
|---|---|
| 6 april 2026 | Uiterste datum waarvoor Microsoft vraagt te migreren naar message trace via Graph |
| 8 april 2026 | Begin van de uitfasering van message trace en message trace detail via de Reporting Web Service |
Andere cloudomgevingen krijgen volgens de post een eigen uitfaseringstijdlijn. De methodedocumentatie vermeldt de Graph-API op dit moment alleen voor de Global service; US Government L4/L5 en China (21Vianet) staan als niet beschikbaar. Nieuw aangemaakte Exchange Online-organisaties hebben volgens de post standaard al geen toegang meer tot message trace via de Reporting Web Service.
Wat dit betekent voor scripts
Voor een beheerder die alleen de V2-cmdlets gebruikt, verandert er functioneel weinig: Get-MessageTraceV2 en Get-MessageTraceDetailV2 bieden dezelfde tweedeling als de Graph-methoden en vallen onder hetzelfde quotum. Voor eigen toepassingen die nu de Reporting Web Service aanroepen, is de Graph-route het aangewezen alternatief. Daarbij horen drie praktische gegevens: de service principal is een harde voorwaarde met een provisioning-wachttijd, de resource staat onder beta, en één query omvat hoogstens 10 dagen en hoogstens 5.000 resultaten per pagina.
De belangrijkste conclusie voor februari 2026 is praktisch: de nieuwe API is in de WW-omgeving beschikbaar, en voor de oude route staat in dezelfde omgeving een begindatum voor uitfasering in april. Geplande taken die afleverfouten rapporteren, helpdesktools die een trace opvragen en koppelingen met ticketsystemen zijn de plekken waar de Reporting Web Service in de praktijk nog voorkomt.
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
- Graph-based message trace API onboarding guide – Microsoft Learn
- List messageTraces – Microsoft Graph beta – Microsoft Learn
- exchangeMessageTrace: getDetailsByRecipient – Microsoft Graph beta – Microsoft Learn
- exchangeMessageTraceDetail resource type – Microsoft Graph beta – Microsoft Learn
