Edit

Pull notifications about mailbox events by using EWS in Exchange

  • Article

Find out how to use the EWS Managed API or EWS to subscribe to pull notifications and get events.

EWS in Exchange uses pull notifications to enable clients to request (or pull) notifications about changes to the mailbox from the server to the client.

If you're subscribing to pull notifications by using the EWS Managed API, you subscribe to and get pull notifications by using the SubscribeToPullNotifications method. You then get events from the server by using the GetEvents method.

To subscribe to pull notifications by using EWS, you create a subscription by using the Subscribe operation, parse the response, and then get the notifications by using the GetEvents operation.

After the client receives notifications of items that are changed or created on the server, it can then synchronize the changes.

Subscribe to and get pull notifications by using the EWS Managed API

The following code example shows how to use the SubscribeToPullNotifications method to subscribe to pull notifications for all events in the Inbox folder. The example then uses the GetEvents method to retrieve events from the server. In this example, we assume that service is a valid ExchangeService binding.

// Subscribe to pull notifications in the Inbox.
PullSubscription subscription = service.SubscribeToPullNotifications( 
    new FolderId[] { WellKnownFolderName.Inbox }, 30, null, 
    EventType.NewMail, EventType.Created, EventType.Deleted,
    EventType.Modified, EventType.Moved, EventType.Copied, EventType.FreeBusyChanged); 
 
// Call GetEvents to retrieve events from the server. 
GetEventsResults events = subscription.GetEvents();

After you receive an event from the server, you can synchronize those changes with the server. Use one of the unsubscribe methods specified in How do I unsubscribe to notifications? to end the subscription with the server when the subscription is no longer needed.

Subscribe to pull notifications by using EWS

The following example shows the XML request to send to the server to subscribe to all EventTypes in the Inbox folder by using the Subscribe operation. This is also the XML request that the EWS Managed API sends when subscribing to pull notifications by using the SubscribeToPullNotifications method.

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <t:RequestServerVersion Version="Exchange2016" />
  </soap:Header>
  <soap:Body>
    <m:Subscribe>
      <m:PullSubscriptionRequest>
        <t:FolderIds xmlns="http://schemas.microsoft.com/exchange/services/2006/types">
            <t:DistinguishedFolderId Id="inbox" />
        </t:FolderIds>
        <t:EventTypes>
          <t:EventType>CopiedEvent</t:EventType>
          <t:EventType>CreatedEvent</t:EventType>
          <t:EventType>DeletedEvent</t:EventType>
          <t:EventType>ModifiedEvent</t:EventType>
          <t:EventType>MovedEvent</t:EventType>
          <t:EventType>NewMailEvent</t:EventType>
        </t:EventTypes>
        <t:Timeout>5</t:Timeout>
      </m:PullSubscriptionRequest>
    </m:Subscribe>
  </soap:Body>
</soap:Envelope>

The following XML example shows the SubscribeResponse message that is sent from the server to the client in response to the Subscribe operation request. The inclusion of the NoError value for the ResponseCode element means that the subscription was created successfully. The SubscriptionId element uniquely identifies the pull notification subscription on the server. The Watermark element represents a bookmark in the mailbox event queue.

<?xml version="1.0" encoding="utf-8"?>
<SubscribeResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                   xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <ResponseMessages xmlns="http//schemas.microsoft.com/exchange/services/2006/messages">
    <SubscribeResponseMessage ResponseClass="Success">
      <ResponseCode>NoError</ResponseCode>
      <SubscriptionId>d581ab79-a2ec-4653-9c8e-564d7cfc1d8c</SubscriptionId>
      <Watermark>AAAAAGUhAAAAAAAAAQ==</Watermark>
    </SubscribeResponseMessage>
  </ResponseMessages>
</SubscribeResponse>

After creating the subscription, you can now get events by using the SubscriptionId that is returned in the SubscribeResponse message.

Get pull notifications by using EWS

The following XML example shows the GetEvents operation request message that is sent from the client to the server to get notifications for the SubscriptionId that is returned in the SubscribeResponse message. For the first GetEvents request, use the Watermark returned in the Subscribe response. For subsequent GetEvents requests, use the last Watermark that was returned in the previous GetEvents request.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <t:RequestServerVersion Version="Exchange2016" />
  </soap:Header>
  <soap:Body>
    <m:GetEvents>
      <m:SubscriptionId>d581ab79-a2ec-4653-9c8e-564d7cfc1d8c</m:SubscriptionId>
      <m:Watermark>AAAAAGUhAAAAAAAAAQ==</m:Watermark>
    </m:GetEvents>
  </soap:Body>
</soap:Envelope>

The following XML example shows the GetEvents response message that is sent from the server to the client. Each GetEvents response includes information about one or more events. A Watermark is returned for each event. The last Watermark must be saved and used in the next GetEvents request. If no store events have occurred since the last GetEvents request, a status event is returned.

<?xml version="1.0" encoding="utf-8"?>
<GetEventsResponseType xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                       xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <ResponseMessages xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">
    <GetEventsResponseMessage ResponseClass="Success">
      <ResponseCode>NoError</ResponseCode>
      <Notification>
        <SubscriptionId xmlns="http://schemas.microsoft.com/exchange/services/2006/types">d581ab79-a2ec-4653-9c8e-564d7cfc1d8c</SubscriptionId>
        <PreviousWatermark xmlns="http://schemas.microsoft.com/exchange/services/2006/types">AAAAAGUhAAAAAAAAAQ==</PreviousWatermark>
        <MoreEvents xmlns="http://schemas.microsoft.com/exchange/services/2006/types">false</MoreEvents>
        <NewMailEvent xmlns="http://schemas.microsoft.com/exchange/services/2006/types">
          <Watermark>AAAAAHMhAAAAAAAAAQ==</Watermark>
          <TimeStamp>2013-09-15T21:37:01Z</TimeStamp>
          <ItemId Id="AAAtA=" ChangeKey="CQAAAA==" />
          <ParentFolderId Id="AQAtAEFkbWA==" ChangeKey="AQAAAA==" />
        </NewMailEvent>
      </Notification>
    </GetEventsResponseMessage>
  </ResponseMessages>
</GetEventsResponse>

After you receive an event from the server, synchronize the changes to the client. Use the Unsubscribe operation to end the subscription with the server when the subscription is no longer needed.

Next steps

After you're received notifications, you can sync the folder hierarchy or sync the contents of the folder that changed.

See also