API reference · Email
POST/api/email/webhooks/microsoft
Product availabilityAlgaPSA

Receive Microsoft Graph email webhook

Receives Microsoft Graph change notifications for monitored mailboxes. Standard session and API-key middleware are bypassed. The handler supports validation token echo, parses Microsoft notification batches, resolves provider and tenant by matching notification subscriptionId to microsoft_email_provider_config.webhook_subscription_id, validates clientState against the stored webhook_verification_token when configured, extracts message IDs, and enqueues pointer-only jobs into the unified inbound email queue. The tenantId in the Microsoft payload is informational and is not trusted for tenant resolution.

Query parameters

validationtokenstringOptional
Microsoft Graph subscription validation token. The handler also accepts validationToken with camel-case spelling.
validationTokenstringOptional
Camel-case variant of the Microsoft Graph validation token.

Request body

Content type: application/json · schema MicrosoftGraphWebhookBody

valuearray of MicrosoftGraphNotificationRequired
Batch of Microsoft Graph change notifications.
itemsobject
changeTypestringRequired
Microsoft Graph change type, typically created for new mail.
clientStatestring
Opaque verification token that must match microsoft_email_provider_config.webhook_verification_token when configured.
resourcestringRequired
Graph resource path, for example /users/{userId}/messages/{messageId}.
resourceDataobjectRequired
@odata.typestring
OData resource type, such as #microsoft.graph.message.
@odata.idstring
OData resource identifier.
idstring
Microsoft Graph message ID. If absent, the handler extracts it from resource.
subjectstring
Optional message subject supplied by Microsoft Graph.
subscriptionExpirationDateTimestring
Microsoft Graph subscription expiry timestamp.
subscriptionIdstringRequired
Microsoft Graph subscription ID. Used to resolve microsoft_email_provider_config.webhook_subscription_id.
tenantIdstring
Microsoft tenant GUID from the notification. Informational only; tenant is resolved from DB.

Response body

Success response 200

anyOf (option 1)object
successbooleanRequired
Webhook request was processed successfully.
Enum: true
queuedbooleanRequired
Whether any notification pointer jobs were enqueued.
handoffstringRequired
Queue handoff mechanism used for Microsoft notification pointers.
Enum: unified_pointer_queue
unifiedQueuedCountintegerRequired
Number of notification jobs enqueued.
processedCountintegerRequired
Number of notifications processed.
messageIdsarray of stringRequired
Microsoft Graph message IDs that were enqueued.
itemsstring
anyOf (option 2)object
successbooleanRequired
Webhook request was accepted.
Enum: true
messagestringRequired
Reason no notification jobs were enqueued.
anyOf (option 3)string
Plain text response. For validation requests, this is the validation token echoed verbatim; otherwise it may be OK or Internal Server Error.

Response codes

200
Validation token echoed as text/plain, or JSON success response after notifications are processed or skipped.
500
Unexpected internal server error.
503
One or more notification pointers could not be enqueued.