Server-side filtering options for Microsoft Graph webhook notifications

Question

Server-side filtering options for Microsoft Graph webhook notifications

Surekha Yeddula 60

Hi Team,

I am using Microsoft Graph webhook subscriptions to receive Outlook mail change notifications. Currently, I understand that subscriptions can be created on resources such as /users/{id}/messages or specific mail folders, but I have not found a way to filter notifications based on message properties.

Is there any server-side filtering capability available that would allow notifications to be generated only for emails matching specific criteria, such as:

A particular sender email address
Specific recipients
Subject keywords
Message categories
Custom message properties or extended attributes

My goal is to reduce the number of notifications delivered to the webhook endpoint and receive only notifications relevant to a specific business use case.

If such filtering is not currently supported, is the recommended approach to subscribe to the broader resource and perform all filtering within the webhook processing logic after receiving the notification?

Any guidance or recommended alternatives would be appreciated.

Thank you.

0 comments

2 answers

Your answer

Answer 1

Hani-Ng 11,740 Microsoft External Staff Moderator

Hi Surekha Yeddula

Based on my research and understanding, I would like to share some information that I hope it will be help:

Server-Side Filtering on Message Properties (Current Status)

You are correct that some filtering is possible, it may be restricted. Microsoft Graph provides limited support for the $filter query parameter in the resource URL when creating a subscription for Outlook messages. However, this support is restricted to a very small number of specific properties (such as isRead) and does not cover the common business-filtering scenarios you've described.

Specifically, there is no documented support for server-side subscription filtering based on:

Sender email address (from)
Specific recipients (toRecipients)
Subject keywords
Message categories
Custom or extended properties

Therefore, while the mechanism exists in a limited form, it is not a viable solution for the requirements you've listed.

Optimized Client-Side Filtering

Here is the recommended workflow for a highly performant solution you can try:

1/ Subscribe to the Narrowest Possible Resource.

While you can't filter on most properties, you can filter by folder. If your use case is limited to the Inbox, subscribe there. This is the most effective server-side reduction you can perform. "resource": "/users/{user-id}/mailFolders('Inbox')/messages"

2/ Process the Notification:

Standard Notifications (Default): The payload you receive is very lightweight and contains only the ID of the changed resource, not the message data itself. This design requires your application to make a follow-up GET call to fetch the message details.
Rich Notifications (includeResourceData: true): If you use this option, the notification payload will include the resource data. This avoids the second GET call but results in larger notification payloads.
Fetch only the Properties You Need (for Standard Notifications). This is the most critical optimization. When you make the follow-up GET call for the message, use the $select OData query parameter to retrieve only the properties required for your filtering logic. This drastically reduces payload size and API latency. Example: If you only need to filter by sender and subject, your GET request should be:

GET https://graph.microsoft.com/v1.0/users/{user-id}/messages/{message-id}?$select=from,subject

3/ Apply Your Business Logic.

In your code, inspect the properties you retrieved. If they match your criteria, proceed with your business process. If not, discard the event.

To summarize, comprehensive server-side filtering for Outlook mail webhook notifications is not broadly supported. While very limited support exists for specific properties, it does not cover the common business scenarios of filtering by sender, subject, or categories.

The standard and recommended architecture is to implement the filtering logic on the receiving side (your webhook endpoint), using folder subscriptions and the $select parameter to keep the process as efficient as possible.

The Microsoft Graph team is aware this is a highly requested feature. I recommend you add your voice and vote for it on the Microsoft Graph Feedback Portal, as customer feedback directly influences our roadmap.

I hope this helps. If you have any question, please feel free to ask via comment section!

(Please understand that we're not Microsoft support, this is a user-to-user support forum. Moderators have no backend access and cannot directly intervene in Microsoft products. We provide only technical guidance and best-practice recommendations based on reported issues)

Note: Please follow the steps in our documentation to enable e-mail notifications if you want to receive the related email notification for this thread.

Surekha Yeddula 60 Reputation points

2026-06-02T05:27:04.8766667+00:00

Thanks for high level overview.

My business scenario is as follows:

My inbox receives hundreds of emails, but I am only interested in emails with the subject/Body "Hourly Weather Update", which are expected to arrive once every hour. I do not want notifications for any other emails that land in the inbox.

Is there a way to configure notifications—either standard or rich notifications—so that they are triggered only for these specific "Hourly Weather Update" emails?

Can MAPI properties be leveraged to identify these emails and ensure that notifications are generated exclusively for them while ignoring all other incoming messages?
Hani-Ng 11,740 Reputation points Microsoft External Staff Moderator

2026-06-03T04:30:07.6366667+00:00
Hi Surekha Yeddula

Thank you for your response. According to your concerns:

Can notifications be filtered by Subject/Body?

Unfortunately, neither standard nor rich notifications can be configured to trigger based on the content of the subject or body. The webhook system is designed to notify you that a new email has arrived, but it does not inspect the email's content to decide if a notification should be sent.

Can MAPI properties be used to filter notifications?

While MAPI properties are powerful for querying data (i.e., in a GET request), they cannot be used in a webhook subscription to filter which events generate a notification.

The recommended solution is to use an inbox rule together with folder subscription. Since Graph webhooks cannot perform this type of content-based filtering, the official and most effective solution is to let Exchange Server do the filtering for you.

Create a New Folder: In the user's mailbox, create a dedicated subfolder (ex: named "Test").

Create an Inbox Rule: In Outlook or Exchange, create a new mail rule for the user with the following logic:

Condition: When a message arrives where the subject or body contains "Test"

Action: Move it to the "Test" folder

Subscribe to the Folder (Not the Inbox): Now, create your Microsoft Graph webhook subscription, but instead of pointing it at the noisy Inbox, point it directly at your new, clean folder. To do this, you'll first need the folder's ID, which you can get with a simple Graph API call.

Resource URL for the subscription: "resource": "/users/{user-id}/mailFolders/{folder-id-of-your-new-folder}/messages"

With this setup, the Exchange server itself acts as your filter. The vast majority of emails will remain in the Inbox and will not trigger your webhook. Only the specific "Test" emails will be moved to your dedicated folder.

The webhook, watching only that folder, will fire exclusively when a relevant email arrives. This gives you a zero-noise, highly efficient system that matches your business requirements.

I hope this information and recommendation are helpful.
Hani-Ng 11,740 Reputation points Microsoft External Staff Moderator

2026-06-04T07:59:59.39+00:00

Hi Surekha Yeddula

I just wanted to follow up to see if you need any additional information regarding this matter. Please don’t hesitate to reach out!

Surekha Yeddula 60

I can see that MAPI is possible in graph webhook and iam able to filter the notifications based on the subject.

e.g:
curl -X POST https://graph.microsoft.com/v1.0/subscriptions \

-H "Authorization: Bearer acess token" \

-H "Content-Type: application/json" \

-d '{

"changeType": "created,updated",

"notificationUrl": "https://public address",

"resource": "users/useremail/messages?$select=id,subject,bodyPreview,receivedDateTime&$filter=singleValueExtendedProperties/any(ep: ep/id eq '\''String 0x0037'\'' and ep/value eq '\''Weather'\'')",

"expirationDateTime": "2026-06-05T05:27:00Z",

"clientState": "weather-monitor",

"includeResourceData": true,

"encryptionCertificate": "'"$CERT"'",

"encryptionCertificateId": "weather-cert-01"

}'

Hani-Ng 11,740 Reputation points Microsoft External Staff Moderator

2026-06-05T05:28:08.2366667+00:00
Hi Surekha Yeddula

Thank you for sharing that information.

This is one of the most subtle and important points for developers working with Graph notifications, and your post highlights it perfectly.

You've correctly identified that the Graph API accepts the subscription request with a MAPI property filter. It's a common experience for developers to see that 201 Created response and believe the filter is active.

The key distinction is between the API endpoint validating the request and the back-end notification service actually honoring the filter. For the /messages resource, our experience and the official guidance show that the notification engine doesn't evaluate this kind of filter. It silently falls back to notifying on the base resource, which means you get notifications for all new messages.

There’s a quick test you can run to see this in action:

Keep your current subscription active.

Send a second email to that same mailbox, but with a subject that does not match your filter.

Your webhook continues to receive a notification for the second email. This situation indicates that the filter does not appear to be limiting the notifications.

Because this is an undocumented behavior for this specific scenario, it's not considered a supported feature for production use. Relying on it means it could change at any time without prior notice.

For this reason, I recommended solution remains the Inbox rule + Folder subscription pattern. It's guaranteed to be reliable and is the standard way we solve this exact problem.
Surekha Yeddula 60 Reputation points

2026-06-05T06:51:39.98+00:00

Thanks for the reply. I verified this behavior, and notifications were received only for emails matching the specified subject filter. Notifications were not triggered for other emails that did not meet the filter criteria.
Hani-Ng 11,740 Reputation points Microsoft External Staff Moderator

2026-06-06T10:28:07.54+00:00

Hi Surekha Yeddula

Thank you for your update.

You may start a new thread in Microsoft Tech Community forum to get more insights, the members there could provide you with a better solution. It’s a great platform for deeper technical discussions and connecting with individuals who have hands-on experience and expertise. They’re best positioned to provide guidance and valuable insights on this topic.

Apologies for redirecting you to the related development team support as the moderators in this community have limited resources to check the backend information, and to get the fast and better assistance we requested for it.

Best Regards
Surekha Yeddula 60 Reputation points

2026-06-08T04:23:15.03+00:00

Thanks Hani-Ng
Hani-Ng 11,740 Reputation points Microsoft External Staff Moderator

2026-06-08T07:05:11.94+00:00

Hi Surekha Yeddula

If you are able to find helpful solutions, I would greatly appreciate it if you could share them here so that other users may also gain knowledge.

Thank you and have a nice day.
Surekha Yeddula 60 Reputation points

2026-06-11T04:18:50.5966667+00:00
Hello @Hani-Ng ,

regarding "Subscribe to the Folder (Not the Inbox): Now, create your Microsoft Graph webhook subscription, but instead of pointing it at the noisy Inbox, point it directly at your new, clean folder. To do this, you'll first need the folder's ID, which you can get with a simple Graph API call.

Resource URL for the subscription: "resource": "/users/{user-id}/mailFolders/{folder-id-of-your-new-folder}/messages""

I can create a folder and subscribe users to that folder using application permissions. However, I want to create an inbox rule that automatically moves emails to that folder based on a subject match. Does each user need to create this rule in their own mailbox, or can an administrator configure the rule for all users using OAuth 2.0 application permissions?
Hani-Ng 11,740 Reputation points Microsoft External Staff Moderator

2026-06-15T05:40:26.79+00:00

Hi Surekha Yeddula

An administrator can configure everything centrally using application permissions. Individual users do not need to create the rules themselves.

The Microsoft Graph API is designed for this exact type of administrative, at-scale scenario. You can programmatically create the folder, the inbox rule, and the webhook subscription on behalf of any user, all from a single administrative application.

With the correct application permissions, your service can manage this entire workflow centrally, making it a fully scalable and automated solution. You can find more details in the official documentation here: Create rule - Microsoft Graph v1.0 | Microsoft Learn
Hani-Ng 11,740 Reputation points Microsoft External Staff Moderator

2026-06-16T07:14:03.88+00:00

Hi Surekha Yeddula

Just quickly check in to see if you have any further question. Please feel free to let me know

Answer 2

Server-side filtering for Microsoft Graph Outlook change notifications is supported in a limited way via the $filter query parameter on the resource when creating the subscription, but not for all the criteria listed.

For Outlook resources (messages, events, contacts):

Subscriptions must target supported resource paths such as:
- /users/{id}/messages
- /me/messages
- /users/{id}/mailFolders/{id}/messages
To include resource data in the notification payload, the subscription must specify:
- includeResourceData: true
- resource: the resource URL including $select for the properties to return
- encryptionCertificate and encryptionCertificateId
When specifying resource, $select must be used to explicitly list the Outlook message properties to include. $filter can be added to refine which changes generate notifications.
$filter can be used to refine conditions for notifications. The documentation provides an example for messages based on the isRead property to get only unread messages in a folder. In that example:
- A message added or marked unread triggers Created.
- Reading or marking as read triggers Deleted.
- Other property changes trigger Updated.
This shows that server-side filtering is supported for some message properties via $filter, but the context only documents isRead explicitly. The context does not document filters for sender, recipients, subject keywords, categories, or custom/extended properties for Outlook message subscriptions.
For other resources (for example, Microsoft Entra Health monitoring alerts), the same pattern applies: $filter can be used in notificationQueryOptions to narrow notifications (for example, alertType), but this is specific to that resource type.

Based on the provided information:

Server-side filtering for Outlook message change notifications is supported via $filter, but the documented example is limited to the isRead property.
The context does not document server-side filtering by sender, recipients, subject keywords, categories, or custom/extended properties for Outlook messages.
When such filters are not available or documented, the recommended approach is to subscribe to the broader resource (for example, a folder or mailbox) and perform business-specific filtering in the webhook processing logic after receiving notifications.

In practice, this means:

Use $filter where supported and documented (for example, unread messages via isRead eq false) to reduce volume.
Use $select to limit the properties included in rich notifications.
Implement additional filtering for sender, recipients, subject, categories, or custom properties in the webhook endpoint code after decrypting and reading the resource data.

References:

Share via

Server-side filtering options for Microsoft Graph webhook notifications

2 answers

Your answer