Notification subscriptions, mailbox events, and EWS in Exchange

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

Last modified: June 19, 2014

Applies to: Exchange Online | Exchange Server 2013 | Office 365

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.

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.

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.

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 How to: 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 How to: 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.

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 How to: 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 How to: 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

Streaming

GetStreamingEvents operation

StreamingSubscriptionConnection.AddSubscription method

Creates a hanging get request on the server, which is responded to when events occur.

Pull

GetEvents operation

PullSubscription.GetEvents method

Gets pull notification events from the server.

Push

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.

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

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

Streaming

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.

Pull

Timeout element

timeout parameter of the SubscribeToPullNotification method

After the timeout value elapses, the server deletes the subscription.

Push

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.

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.

Show:
© 2014 Microsoft