Notification subscriptions, mailbox events, and EWS in Exchange

Find out about notification subscriptions and mailbox event in EWS in Exchange.

You can use both the EWS Managed API and Exchange Web Services (EWS) to subscribe to receive notifications when events occur in a mailbox, or in one or more of the folders in a mailbox. Three subscription types are available: streaming notifications, pull notifications, and push notifications. Each of these subscription types uses different techniques to receive or retrieve the notifications.

Getting notifications - what are my options?

EWS includes three subscription types that work independently to notify the client of changes on the server. No matter which subscription type you choose, you'll have access to all the same notification events in the end - it's just a matter of how you get them.

Table 1. Subscription types

Option Description Is it right for me?
Streaming notifications
Notifications that are sent by the server through a connection that remains open for a specified period of time.
Streaming notifications are generally recommended for most applications. They're similar to pull and push notifications, and offer the best of both worlds. After you establish your notification subscription, the connection remains open for up to 30 minutes to allow the server to push notifications back to the client. No need to request updates, like you would with a pull subscription, and you don't have to create a web service listener application like you would with a push subscription.
Pull notifications
Notifications that are requested (or pulled) by the client.
Pull notifications are generally most appropriate for loosely coupled clients, where the client is not reliably connected to the network. Pull notifications can create excess traffic between the client and the server because the client is sending frequent requests to the server to retrieve notifications, and not all requests result in notifications retrieved.
Push notifications
Notifications that are sent (or pushed) by the server to a client-side web service via a callback address.
Generally, push notifications provide for smaller notification latency than pull notifications and are suited for tightly coupled clients to which the server has reliable access and the client is IP addressable. However, push notifications have fallen out of favor since the advent of streaming notifications in Exchange 2010. If possible, we recommend that you use streaming notifications instead of push notifications going forward. Push notifications require that you write a listener application, which is where the notifications are pushed to. This has a slight benefit over pull notifications in that it reduces wire traffic, but it adds overhead by requiring a separate application.

What EWS events can I subscribe to?

The types of EWS events that clients subscribe to are defined by the EventType enumeration for the EWS Managed API or the EventType element for EWS. The following EWS events are available for subscription:

Another EWS event type, the Status event, is defined by the EventType element, but you don't subscribe to this event. Instead, it's sent by the server to check the status of the client for streaming and push notifications only. The client needs to respond to this event needs or the client will time out.

A single user action often results in the creation of multiple notifications. To illustrate this, the following figure shows some common scenarios and the notifications created for each one. Client settings have an impact on the notifications received, so this is not an exhaustive list of all the configuration options and resulting notifications.

Figure 1. Event types returned by notification subscriptions

A table that shows the notifications sent in common user scenarios, such as receiving new email, creating a new folder, moving a folder, and so on.

Figure 1 simplifies the notification process. In reality, multiple notifications (even multiple notifications of the same type) can be created for a single user action. For example, in the case of a folder move operation, three folder events are created: one for the folder being modified, one for the old parent folder, and one for the new parent folder. Because numerous events can be fired for a single operation, we recommend that you build a wait time of a few seconds into your synchronization operations, so that you only synchronize when the action is complete, instead of partway through the operation.

It's also important to realize that the configuration settings that each user chooses will affect which notifications are created. For example, some users' free busy data is updated automatically and the FreeBusyChanged event is created when a new meeting request is received, even before they've read the item. For other users, free busy data isn't updated and the FreeBusyChanged event isn't created until after the meeting has been accepted. These settings can have a considerable impact on the notifications created by the server.

How do EWS notifications work?

EWS notifications are handled on a subscription basis. Typically there's one subscription per mailbox, and within the mailbox subscription you can subscribe to some or all folders. You decide what kind of notification to subscribe to (streaming, pull, or push) and what kind of events you'd like to receive (NewMail, Created, Deleted, Modified, etc.), and then you create a subscription. The EWS events are then sent asynchronously from the mailbox server to the client. (History lesson: events are synchronous in Exchange 2007 - and events are stored on the Client Access server in Exchange 2010, but no more!).

Depending on the type of subscription you have, the ways in which the notifications are sent to the client vary. This section describes how each type of subscription works in more detail.

EWS streaming notifications

Streaming notifications rely on a hanging get request on the server to keep a streaming subscription connection open, so that any events that occur while the connection is active are streamed to the client immediately. Multiple notifications can be sent over the course of a single connection, and the connection stays open until the interval expires, or for a maximum of 30 minutes. After the connection expires, the client sends the hanging get request again. Figure 2 shows how streaming subscriptions and streaming notifications work.

Figure 2. Streaming notification overview

An illustration that shows how streaming notifications work. To set up streaming notifications: 1. Subscribe, 2. Open connection, 3. Wait for events, 4. Receive events, repeat 3 and 4, 5. Close or keep connection, 6. Unsubscribe or timeout.

For information about creating streaming notifications, see Stream notifications about mailbox events by using EWS in Exchange.

EWS pull notifications

Pull notifications rely on the client asking for the notifications on an interval that the client manages. This can result in GetEvents responses with no notifications. Figure 3 shows how pull subscriptions and pull notifications work.

Figure 3. Pull notification overview

An illustration that shows how pull notifications work. To set up pull notifications: 1. Subscribe, 2. Send GetEvents, 3. Receive response, repeat 2 and 3, 4. Close or keep connection, 5. Unsubscribe or timeout.

For information about creating pull notifications, see Pull notifications about mailbox events by using EWS in Exchange.

EWS push notifications

Push notifications rely on the server pushing notifications back to the client. There's only traffic if there's a notification. Figure 4 shows how push subscriptions and push notifications work.

Figure 4. Push notification overview

An illustration that shows how push notifications work. To setup push notifications: 1. Create listener, 2. Subscribe, 3. Wait for events, 4. Receive events, 5. Send "OK" response, repeat 3, 4, and 5, 6. Unsubscribe or timeout.

If you are using push notifications with Exchange 2010, consider upgrading your application to use streaming notifications, so that you don't need a separate application to receive the events.

How do I subscribe to notifications?

Depending on the type of subscription you'd like to create, you have a number of options to choose from for subscribing to notifications.

Table 2. Operations and methods for subscribing to notifications

Subscription type EWS operation EWS Managed API methods What it does
Subscribe operation
ExchangeService.BeginSubscribeToStreamingNotifications method
ExchangeService.BeginSubscribeToStreamingNotificationsOnAllFolders method
ExchangeService.SubscribeToStreamingNotificationsOnAllFolders method
Creates a request to subscribe to streaming notifications.
Subscribe operation
ExchangeService.BeginSubscribeToPullNotifications method
ExchangeService.BeginSubscribeToPullNotificationsOnAllFolders method
ExchangeService.SubscribeToPullNotifications method
ExchangeService.SubscribeToPullNotificationsOnAllFolders method
Creates a request to subscribe to pull notifications.
Subscribe operation
ExchangeService.BeginSubscribeToPushNotifications overloaded method
ExchangeService.BeginSubscribeToPushNotificationsOnAllFolders overload method
ExchangeService.SubscribeToPushNotifications overloaded method
ExchangeService.SubscribeToPushNotificationsOnAllFolders overloaded method
Creates a request to subscribe to push notifications.

How do I get EWS events?

After the subscription is created, the way in which the actual events are sent to the client depends on the subscription type.

For streaming notifications, a streaming subscription connection must be created, and then the subscription is added to the connection. You can read more about this process in Stream notifications about mailbox events by using EWS in Exchange.

For pull notifications, the subscription object was initialized when the subscription was created, so you just have to call the GetEvent method or operation to retrieve the events from the server. You can read more about this in Pull notifications about mailbox events by using EWS in Exchange.

The following table lists the operations and classes required to retrieve events.

Table 3. Elements and classes for creating a connection and getting events

Subscription type EWS operation EWS Managed API method What it does
GetStreamingEvents operation
StreamingSubscriptionConnection.AddSubscription method
Creates a hanging get request on the server, which is responded to when events occur.
GetEvents operation
PullSubscription.GetEvents method
Gets pull notification events from the server.
Not applicable.
Not applicable.
Push notifications are automatically sent to the web service listener (the callback URL specified in the subscription request). No additional methods or operations need to be called.

How do I unsubscribe to notifications?

The following table lists the ways in which you can unsubscribe to each type of subscription.

Table 4. Operations and methods for unsubscribing to notifications

Subscription type EWS EWS Managed API
Unsubscribe operation
StreamingSubscription.BeginUnsubscribe method
StreamingSubscription.EndUnsubscribe method
StreamingSubscription.Unsubscribe method
Unsubscribe operation
PullSubscription.BeginUnsubscribe method
PullSubscription.EndUnsubscribe method
PullSubscription.Unsubscribe method
Return Unsubscribe in the StatusFrequency element of the SendNotificationResponseMessage
Not applicable. Let the subscription time out instead.

Alternatively, you can let each of the subscriptions time out.

Table 5. Subscription time-outs

Subscription type Timeout value in EWS Timeout value in the EWS Managed API Timeout handling
ConnectionTimeout element
lifetime parameter of the StreamingSubscriptionConnection constructor
For the EWS Managed API, after the timeout value elapses, the OnDisconnect event is raised. If the StreamingSubscriptionConnection.Open method is not called, the connection is closed.
For EWS, after the timeout value elapses, the GetUserConfigurationResponse message returns a ConnectionStatus value of Closed.
Timeout element
timeout parameter of the SubscribeToPullNotification method
After the timeout value elapses, the server deletes the subscription.
StatusFrequency element
frequency parameter of the SubscribeToPushNotification method
If the server does not receive a response to a push notification or status ping, it retries sending the notification several times before it stops sending the notifications. For more information, see StatusFrequency.

Can I limit subscriptions?

In an on-premises deployment, you can limit the number of subscriptions per user with the EwsMaxSubscriptions throttling parameter of the throttling policy. That policy can be applied to all users or just specific users. The EwsMaxSubscriptions throttling policy is not configurable for Exchange Online.

In this section

See also