How should I handle Microsoft message webhooks when emails move between folders?

Situation

A Microsoft mailbox can generate message notifications when an email is moved between folders. Webhook receivers should process message events idempotently and should not assume that a notification alone represents a brand-new email.

Microsoft Graph-Backed Accounts

For Microsoft Graph-backed accounts, the Nylas message.id is derived from Microsoft's immutable message ID. The Nylas message.id remains stable when an email moves between folders and can be used as the primary deduplication key.

A folder move will arrive as message.created even though the message already exists. Process both message.created and message.updated with idempotent upsert logic:

1. Use the Nylas message.id to locate the existing record.

2. Create the record only when that ID is not already stored.

3. Otherwise, update the existing record with the notification payload.

Note: Moving an email out of an un-synced folder (or a folder outside the initial sync backfill window) into a synced folder causes Nylas to discover the message for the first time and fire message.created. Compare the email's original date timestamp against created_at to identify relocated historical messages.

Exchange via EWS

For Exchange on-premises accounts connected through EWS, message IDs can change when messages move between folders. Do not rely on message.id alone as a cross-folder deduplication key for these accounts. See Microsoft provider guidance.

Include RFC 5322 Headers When Needed

Customized message webhook payloads can include either:

• basic_headers: For Message-ID, In-Reply-To, and References. Use this when threading or an additional RFC 5322 identifier is sufficient.

• headers: When the full set of RFC headers is required.

basic_headers and headers are mutually exclusive. Customized notifications use the .transformed event suffix, so receivers must handle event types such as message.created.transformed and message.updated.transformed. See Specify fields for webhook notifications.

Webhook Delivery Safety

Nylas may retry notification deliveries if your server times out. Deduplicate retries using the top-level notification id (which stays identical across retry attempts), not data.object.id.

Note that delivery-level deduplication is separate from message handling—a single message will legitimately produce multiple events (e.g., created and updated) with different top-level IDs as its state changes. See Handle duplicate webhook deliveries.

Docs for reference:

1. Handle duplicate webhook deliveries

2. Microsoft provider guidance

3. Specify fields for webhook notifications

Updated August 20, 2026 12:29