Exchange API-spotting

Play Exchange 2010 Mailbox Items on Your Phone By Using the EWS Managed API

2009-11-05T19:29:01Z

The Unified Messaging Play-On-Phone feature is now exposed through Exchange Web Services in Microsoft Exchange Server 2010. This feature is described in the EWS schema and WSDL files. What will be of more interest to you is that the Play-on-Phone feature is available in the Exchange Web Services Managed API 1.0. Now you can create custom applications that can read your mailbox items to you on your phone. The EWS Managed API implementation is very straightforward. Additionally, if you plan to handle the XML in your code, the EWS XML is also intuitive for customers who want to construct the XML with Microsoft .NET, Java, a scripting language, or any other language that can send and receive HTTP messages.

The following example shows EWS Managed API code that requests that an item be played on a phone, gets the status of the phone call, and then disconnects the phone call.

static void PlayItemOnPhone (ExchangeService service, ItemId itemId, string dialstring)
{
    PhoneCall call = service.UnifiedMessaging.PlayOnPhone(itemId, dialstring);
    Console.WriteLine("Call Number: " + dialstring);
    Console.WriteLine("Call Status: " + call.State + "\n\r");

// Create a timer that will start immediately. Timer will call callback every 2 seconds.
Timer timer = new Timer(RefreshPhoneCallState, call, 0, 2000);

Console.WriteLine("PRESS ENTER TO END THE PHONE CALL AND CALL STATUS UPDATES");
Console.ReadLine();

    // Disconnect the phone call if it is not already disconnected.
    if (call.State != PhoneCallState.Disconnected)
    {
        call.Disconnect();
    }

// Clean up the timer.
timer.Dispose();
}

// Callback method for refreshing call state for the phone call.
static void RefreshPhoneCallState(object pCall)
{
    PhoneCall call = (PhoneCall) pCall;
    call.Refresh();
    Console.WriteLine("Call Status: " + call.State);
}

The PlayItemOnPhone method example has three parameters:

Service - The service binding that identifies the URL of the Exchange Web Services endpoint.
ItemId – The item identifier of the item that will be played on the phone.
dialstring - The dial string of the phone number on which the item is played. The dial string can be set to an SMTP address so that the item is played on Microsoft Office Communicator.

The example uses three EWS operations: PlayOnPhone, GetPhoneCallInformation, and DisconnectPhoneCall. PlayOnPhone is called once, GetPhoneCallInformation may be called many times, and DisconnectPhoneCall may never be called, as the phone call can be disconnected by simply hanging up the phone (of course).

After you are connected to your mailbox via the Play-On-Phone feature, you have an entry point to Outlook Voice Access. After the item is read to you, you can enter the Outlook Voice Access feature. For more information about Outlook Voice Access, see Getting Started with Outlook Voice Access.

Try out the EWS Managed API Play-on-Phone feature in your next EWS client application.

Learn about the Exchange 2010 Developer Story Today!

2009-11-04T20:48:00Z

We’ve just finished our 6 part series of webcasts on six key topics that developers need to know about as they start planning for moving their applications to Exchange 2010. Those webcasts are now available as on-demand webcasts. We've updated the webcast links below to point to our on demand videos so check them out today! If you’d like a bit more human contact than these webcasts, then come join us at TechEd in Germany or Exchange Connections in Las Vegas next week; or the Microsoft Professional Developers Conference in LA November 17-19^th where we’ll have great Exchange 2010 Web Services sessions and program managers from the Exchange Web Services team there to answer your questions and get your applications Exchange 2010-ready.

Don’t miss the Exchange 2010 Developer Webcasts!

2009-10-08T16:43:00Z

We are excited about the Exchange 2010 developer experience and we think you will be too. Over the next two weeks we’ll be doing six webcasts filled with information to help our partners and customers understand what Exchange 2010 means for them. David, Chris and I just posted an introductory video to give you an overview of why we’re excited about Exchange 2010 and show off a cool application built on Exchange 2010 and the Exchange Web Services API. Check out the video and then plan to attend the upcoming webcasts, where we will go much deeper into the technical details that you’ll want to know as you think about moving your applications to Exchange 2010 and Exchange Web Services.

View the webcast now- Exchange Server 2010 Development (Part 1 of 6): Migrating Applications to Exchange Web Services

View the webcast now - Exchange Server 2010 Development (Part 2 of 6): A Deep Dive into Using Autodiscover Service in Exchange Web Services

View the webcast now - Exchange Server 2010 Development (Part 3 of 6): A Deep Dive into Impersonation and Delegation in Exchange Web Services

View the webcase now - Exchange Server 2010 Development (Part 4 of 6): A Deep Dive into Exchange Web Services Notifications (Push/Pull)

View the webcast now - Exchange Server 2010 Development (Part 5 of 6): A Deep Dive into the Exchange Web Services Managed API

View the webcast now - Exchange Server 2010 Development (Part 6 of 6): Best Practices for Building Scalable Exchange Server Applications

Exchange Impersonation vs. Delegate Access

2009-06-15T22:15:49Z

There has been some confusion about the different methods that can be used to access a mailbox. Developers are asking: What method should I use? When should I use it? What are the differences between the different methods? This post will give you a quick comparison of the two most common ways, other than a direct log on, to access a mailbox: Exchange Impersonation and delegate access.

Exchange Impersonation vs. Delegate Access

Exchange Impersonation is used in scenarios in which a single account needs to access many accounts. Line-of-business applications that work with mail typically use Exchange Impersonation. An application can be written to display mailbox data such as number of unread items, calendar, and so on. The application can use a dedicated service account to access multiple users’ mailboxes to display their respective data.

Exchange Impersonation is different than Windows Impersonation. Windows Impersonation is an operating system concept that requires you to set Kerberos constrained delegation. Exchange Impersonation is a simpler authorization mechanism that is designed for use only within Exchange Web Services (EWS). For more information about Windows Impersonation, see Client Impersonation on MSDN.

Delegate access is used in scenarios in which there needs to be a one-to-one relationship between users. One common application of delegate access is the sharing of calendars between users, such as when an admin manages an executive’s calendar, or a when handful of individuals working on a project need to coordinate calendars.

Another example of delegate access is resource mailbox management. Resources, such as conference rooms, can be managed by one or more people. Resources are represented by mailboxes, but not in the traditional sense. Resource mailboxes do not have owners; therefore, they can only be accessed by mail-enabled users to whom delegate access is granted.

The following table lists the differences between Exchange Impersonation and delegate access.

	Exchange Impersonation	Delegate Access
Administered by	Administrator	User
Used by	Exchange Web Services	Any mailbox client
Configuration	Per impersonator	Per shared mailbox
Rights	Broad	Granular
New account creation	Can be automated	ACLs stamped

Administration

An administrator is able to configure impersonation on behalf of a service account, and grant that service account impersonation rights over many mailboxes. Individual users cannot manage who does or does not have impersonation rights over their mailboxes.

Individual users can grant and remove delegate access to their own mailboxes through several mailbox clients, such as Microsoft Outlook, Outlook Web Access, or Exchange Web Services-based clients. A mailbox owner does not need administrator rights to grant another user delegate access to their mailbox.

Auditing

There is no true auditing for either Exchange Impersonation or delegate access. Any mail that is modified by using impersonation will appear to the mailbox as if it was modified by the user who was impersonated. No log is left behind of the impersonation access.

^†For delegate access, there is partial auditing, in that any mail that is sent by a delegate on behalf of the mailbox owner is displayed as “Sent on behalf of.”

Usage

Exchange Impersonation can only be used through Exchange Web Services. The caller (authenticated user) indicates which user they want to impersonate in the SOAP header. For more information about how to use Exchange Impersonation, see Using Exchange Impersonation on MSDN.

Delegate access can be used through any mailbox client, including Outlook and Exchange Web Services-based clients. For more information about delegate access, see Exchange Web Services and Delegate Access on MSDN.

Rights

A user or account that has been granted impersonation rights will have the same rights as the user whom they are impersonating. Typically, service accounts are given the ability to impersonate the mailbox owner. In that case, the impersonating account has full mailbox rights, just as the mailbox owner does.

With delegate access, the delegate can be granted more granular rights, up to and including full mailbox access. Delegate access can also be configured per folder, or per mailbox. For example, a user can grant the delegate read-only access to the Inbox, read-write access to a calendar folder, and so on.

Configuration

Exchange Impersonation is generally configured as one-to-many: one service account to many user accounts. You can configure an account to impersonate a broad set of users, such as an entire mailbox database. For more information about how to configure impersonation, see Configuring Exchange Impersonation on MSDN.

For delegate access, there is no option to set up a single delegate for multiple mailboxes. A relationship must be established for each user who needs to access a given mailbox.

New Accounts

You can configure Exchange Impersonation to allow new accounts that are created to automatically be impersonated by service accounts. Setting up accounts to impersonate any user within a mailbox database can reduce your configuration overhead.

You must explicitly grant delegate access for any new users who are added.

The Exchange 2010 Beta SDKs are Here!

2009-06-05T00:18:54Z

The Exchange Developer Documentation team is happy to announce the release of the Exchange 2010 Beta SDKs. That's right, I said SDKs -- as in, more than one! For earlier product releases, all Exchange developer documentation is included in a single SDK. For Exchange 2010, documentation for each technology area is published in a separate SDK, making it quicker and easier for you to find information that you need. The following SDKs are available online for Exchange 2010 Beta:

The Exchange Web Services Managed API 1.0 SDK is also available online, and contains information that can help you use EWS to develop applications for Exchange 2007 SP1 or Exchange 2010.

To learn more about the new features for developers in Exchange 2010 Beta and the new SDKs, check out Thom Randolph's article Introducing the Exchange 2010 Beta SDKs. Also, be sure to review the Guide to Exchange 2010 Development Technologies, which explains the organization of the SDKs and contains information about the development technologies that are supported in Exchange 2010. Get going today and take advantage of the many cool new features available in Exchange 2010 Beta!

Introducing the EWS Managed API!

2009-04-15T20:26:35Z

Developing applications with Exchange Web Services just got MUCH easier, thanks to the release of the Microsoft Exchange Web Services (EWS) Managed API 1.0 Beta — a new managed-code API that's easy to learn, simple to use, and efficient to code against. Whether you're an experienced EWS developer, you’re new to Exchange development, or you’re somewhere in between, the EWS Managed API is made for you! Say goodbye to the large amounts of code and awkward patterns often required to use EWS via autogenerated proxy classes, and revel in the simplicity and efficiency of the new EWS Managed API!

Want to learn more? Check out David Claux's article Introducing the Exchange Web Services Managed API 1.0 for a full introduction to this new API. Take advantage of the conceptual material and code examples that are available in the Microsoft Exchange Web Services Managed API 1.0 Beta SDK April 2009. And keep your eye on this blog and the Exchange Developer Center in the coming months for posts and articles that explore various how-to scenarios for the EWS Managed API.

Quick and Dirty UNIX Shell Scripting with EWS

2009-02-05T16:59:00Z

One of the great advantages of Exchange Web Services (EWS) is that you can write applications on just about any platform that can make HTTP requests. This characteristic of web services means that you can integrate EWS in to just about every application or environment you can imagine. This aspect of web services was brought home to me the other day while using my Mac OS X laptop, which I have to test Microsoft Entourage Exchange Web Services Edition Beta against Exchange. I wanted to quickly find the phone number for a colleague. I knew I could find the information in Entourage, but I wanted to be able to get the information without leaving my terminal window, so I dug deep in my memory to my first programming project as a 10 year old on a Unix workstation writing shell scripts (yes, that is how my parents kept me occupied).

First, I needed a suitable utility to make an HTTP request, and preferably one that could perform Windows Integrated authentication, which is the default for EWS. Curl is a great little tool for quickly issuing requests; it is supported cross-platform and has an NTLM authentication stack built in. This cool post shows how to use it for building a Mac OSX Widget that works against EWS. I extracted the necessary line and modified them for our use:

curl -s -u username@contoso.com:password -L https://servername/ews/exchange.asmx -d "$DATA" -H "Content-Type:text/xml" --ntlm

Here is a breakdown of the parameters and their function:

–s parameter tells curl to run silently

-u allows me to pass UPN and password on the command line

-L allows us to specify the URL

-d allows me to specify the body of the request should come from a variable called $DATA

-H allows me to set the content header which is required

–ntlm allows me to specify that Curl should try ntlm auth (--anyauth doesn’t work)

The request is then customized for the alias I want by piping the XML for the resolve names request through sed so that I can replace the alias to resolve with the alias I want to resolve as an argument to the utility that I’m going to call resolvename.

DATA=$(sed 's/alias/'$1'/' resolvenames.txt)

resolvenames.txt

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">

<soap:Body>

<ResolveNames xmlns="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"

ReturnFullContactData="true">

<UnresolvedEntry>alias</UnresolvedEntry>

</ResolveNames>

</soap:Body>

</soap:Envelope>

Getting this far is pretty easy and you are left with a simple utility which takes in an alias as a parameter, formats the request with the alias, and makes the request. You can now take this output and pipe it to some utility which can consume it, ideally one that can natively handle the output xml.

<?xml version="1.0" encoding="utf-8"?>

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">

<s:Header>

<h:ServerVersionInfo MajorVersion="8" MinorVersion="1" MajorBuildNumber="200" MinorBuildNumber="1" xmlns:h="http://schemas.microsoft.com/exchange/services/2006/types" xmlns="http://schemas.microsoft.com/exchange/services/2006/types" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"/></s:Header><s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<m:ResolveNamesResponse xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">

<m:ResponseMessages>

<m:ResolveNamesResponseMessage ResponseClass="Success">

<m:ResponseCode>NoError</m:ResponseCode>

<m:ResolutionSet TotalItemsInView="1" IncludesLastItemInRange="true"><t:Resolution>

<t:Mailbox>

<t:Name>Jason Henderson</t:Name>

<t:EmailAddress>jason@contoso.com</t:EmailAddress>

<t:RoutingType>SMTP</t:RoutingType>

<t:MailboxType>Mailbox</t:MailboxType>

</t:Mailbox>

<t:Contact>

<t:Culture>en-US</t:Culture>

<t:DisplayName>Jason Henderson</t:DisplayName>

<t:GivenName>Jason</t:GivenName

><t:CompanyName>Contoso</t:CompanyName>

<t:EmailAddresses>

<t:Entry Key="EmailAddress1">smtp:jason@contoso.com</t:Entry>

</t:EmailAddresses>

<t:PhoneNumbers>

<t:Entry Key="BusinessPhone">555-5555</t:Entry></t:PhoneNumbers>

<t:ContactSource>ActiveDirectory</t:ContactSource>

<t:Department>Web Services</t:Department>

<t:JobTitle>SENIOR PROGRAM MANAGER LEAD</t:JobTitle>

<t:Manager>Bob Manager</t:Manager>

<t:OfficeLocation>55/5555</t:OfficeLocation>

<t:Surname>Henderson</t:Surname>

</t:Contact></t:Resolution>

</m:ResolutionSet>

</m:ResolveNamesResponseMessage>

</m:ResponseMessages>

</m:ResolveNamesResponse>

</s:Body>

</s:Envelope>

Since I did shell scripting before XML parsing was in high demand I don’t have any good XML parsing tools up my sleeve, just good old awk and sed. After a couple of false starts I dropped a mail to my good friend John Muster, author of Unix Made Easy (always at my side when I do any kind of shell scripting) and asked for his help. He quickly obliged with a quick and dirty XML parser using expr that we both admit is ugly and incomplete, but works well enough for parsing out office location, phone numbers, job titles, and any other standard field. The complete listing of the utility I call resolvename is below.

resolvename

DATA=$(sed 's/alias/'$1'/' resolvenames.txt)

curl -s -u jasonhen@contoso.com:password -L https://servername/ews/exchange.asmx -d "$DATA" -H "Content-Type:text/xml" --ntlm | tr -d '<:>' \

| tr ' ' '+' > /tmp/output$$

expr `cat /tmp/output$$` : '.*'$2'$.*$/\t'$2 > /tmp/selection$$

tr + ' ' < /tmp/selection$$

rm /tmp/output$$ /tmp/selection$$

The usage for the utility is: resolvename <alias> <xmlnode>, so for example “resolvename jason JobTitle” returns “Senior Program Manager Lead” or “resolvename jasonhen OfficeLocation” returns my building and office number. Pretty slick if I do say so myself.

Warnings – This code is not even prototype quality. Among numerous other shortcomings, no error codes are handled, and XML parsing only works properly with elements that occur once and have no attributes. If I were going to write a production quality application, I’d probably choose a language like php, python, or perl which have nice xml parsing stacks—but for something quick and dirty that works anywhere that you have curl and a bash environment this fits the bill.

Exchange Web Services Push Notifications Simplified

2008-12-31T02:55:26Z

Using Exchange Web Services push notifications just got a lot easier, thanks to Exchange Server MVP Henning Krause. Henning has created a notification listener project on CodePlex. The listener application handles Exchange Web Services push notifications. The listener uses the WCF service model, and does not rely on IIS. Check it out, provide some feedback, and incorporate EWS push notifications into your Exchange Server client application.

The December SDK is Here!

2008-12-10T23:45:00Z

I am happy to announce that the December 2008 release of the Exchange Server 2007 SP1 SDK is available. And now, a Haiku for you.

Released new content.
Updated topics for you.
Go get the goods here.

MAPI documentation moved to Office

2008-12-04T21:55:38Z

Just a quick note to all you fans of MAPI out there. Based on some discussions we had a while ago, the folks in Office have been putting a LOT of time and effort into improving the MAPI material, and bringing it up-to-date for Office 2007. Well, they’ve finished their work, and the improvements are substantial! Check out the new content on MSDN Library at: http://msdn.microsoft.com/en-us/library/cc765775.aspx. We plan to have a redirection page under Exchange Server for about six months, to remind you where the stuff went.

Thom Randolph (thomr@microsoft.com)

Learn about the Exchange Web Services Managed API and how Exchange is getting “Cloud Ready” at PDC’08

2008-10-16T00:23:00Z

Those of you who have already made plans to catch PDC ’08 in L.A. at the end of October be sure to catch the Exchange Web Services Managed API: Unified Communications Development for Exchange session. This exciting talk will be the coming out party for the managed API; it will be the first time that the API has been shown in public. We’ll have live coding, demo’s, and of course answer your questions on everything Exchange development. I’m looking forward to seeing you in L.A.!

Jason Henderson

Exchange Web Services Update Rollup 4 Roundup

2008-10-07T22:32:00Z

We have just released update rollup 4 (RU4) for Exchange 2007 SP1. This rollup fixes some bugs in Exchange Web Services (EWS), and introduces some behavior changes to EWS to allow customers and partners the flexibility to accomplish some key scenarios. If you have written code against Exchange Web Services, we definitely recommend that you take a look at RU4. The following are the biggest changes that will be coming in the rollup:

- Item IDs are now returned after MoveItem/CopyItem calls.

- Unknown/unsupported item types are returned as Messages.

- Updating tasks can now have correct behavior for Start and Complete Date values.

ItemId of Item Is Returned After a MoveItem/CopyItem Call

Some of our observant developers have noticed that Exchange creates new destination item IDs for items when they are moved between folders. We created a place in the schema to return the destination ID of an item, and in the early stages of Exchange development, this ID was returned. We pulled it out late in the Exchange 2007 development cycle after we determined that the method of determining the destination ID was too resource-intensive. After consistent feedback from customers that this feature was needed so that items could be tracked as they were moved between folders, we implemented a much more performant solution. Now, if you call MoveItem/CopyItem, you’ll be able to identify the new item in the destination folder by looking at the destination ID that is returned by the MoveItem/CopyItem call.

Note: Cross-mailbox or mailbox-to-public folder CopyItem/MoveItem calls will not return destination IDs and RU4 must be applied to both the Client Access Server and the Mailbox Server Role for this feature to work.

Non-IPM.Note.* Items Are Returned as Messages

EWS in Exchange 2007 SP1 uses the <Item> type as the base class for items that are not strongly typed. This design has caused problems for customers who want to reply to item types that have a custom item class, or item types that EWS does not yet support, like IPM.Sharing or IPM.InfoPath. In RU4, all item types that we do not support natively in Exchange Web Services, like Journal, Sharing Requests, InfoPath forms, are returned as <Message> instead of <Item>. This means that you can see all the recipient information on the item, mark it as unread, reply to it, or forward it just like you would a normal item (assuming that the object supports forwarding/replying).

<Item> type still exists as a base class for <Message>, so most applications built on the auto-generated proxy classes will not be affected; however, applications that parse the XML directly could break if they are expecting <Item> rather than <Message>. To minimize the risk of breaking applications, this behavior is only applied when the Exchange2007_SP1 version header is specified.

We don’t take making changes in a rollup that could break applications lightly; our goal is to only change protocol behavior with the introduction of a new version header. However, we felt that this functionality is critical for some of our partners and customers, has a minimal impact on the majority of applications, is the way EWS should have worked in the first place, and can’t wait for the next service pack for Exchange, which could introduce a schema change for a new version header. For more details about this topic, see Robin’s June post that describes the proposed change and asks for feedback.

Updating Recurring Tasks Now Works Correctly

In Exchange 2007 and Exchange 2007 SP1, when a task is updated, such as by marking CompleteDate, the Client Access server shifts the date specified as the complete date according to the offset of its time zone. This is bad because clients are rarely aware of the time zone that the server is operating in. If the Client Access server and the client time zones are far enough apart, tasks could be marked as completed on the wrong day — not good!

The problem is that no time zone information is passed to EWS in tasks, yet a time zone is required when saving/updating/getting tasks to make sure that the task is marked as completed on the correct day. To fix this problem, with RU4, EWS can treat offset date times in a special way when they are the Complete Date, Due Date, or Start Date elements of a task. The offset, for example 10:00:00T-08:00, is used to create a time zone for that offset. This time zone is used when the task is saved so that the date the task was completed is always the date intended.

This post only covers the changes in RU4 that we think are most interesting to Exchange Web Services developers. We will be posting this and additional information in KB articles shortly. We hope you find this information useful and as always appreciate your feedback.

Jason Henderson and Andrew Salamatov

Attention all Exchange Web Services Solution Architects!

2008-09-05T02:48:28Z

If you haven't already, we strongly recommend that you review the Managing the Calendaring and Collaboration Process By Using Exchange Server 2007 Web Services Technical Case Study. In it you will find a technical case study of two internal Microsoft line-of-business applications that were migrated from earlier Exchange technologies to Exchange Web Services. Hopefully these two examples can help guide you in your design of a service-oriented architecture that incorporates Exchange Web Services.

Exchange Server 2007 SP1 SDK update is now being served!

2008-08-15T23:53:01Z

The Microsoft Exchange Server 2007 SP1 SDK has been updated and is now available for your coding pleasure! The Exchange 2007 SP1 SDK is available for download or viewable online. We suggest that you start with the What’s New page to learn about the updates made for the August release. So get rolling on your Exchange development projects with the latest version of the Exchange SDK! And while you’re at it, take some advice from the Autodiscover song.

Transitioning to Exchange Web Services Notifications

2008-07-24T21:39:12Z

Jason Henderson announced in his Exchange Developer Roadmap blog post that we are officially deprecating, among other things, Store Event Sinks and SMTP Event Sinks. This means that Exchange developers will have to rely on Exchange Web Services (EWS) notifications and transport agents to perform many of the tasks previously handled by these event sinks. To help with the transition, I’m going to discuss how to manage the notification subscription lifecycle. Specifically, I’m going to focus on push notifications. I’m going to assume that the reader is familiar with both the Notifications documentation that is available on MSDN (Event Notifications) and the Exchange Web Services API. Also, Inside Microsoft Exchange Server 2007 Web Services is a great book that was written by some of the people who developed Exchange Web Services and has a lot of detailed information on this and other topics.

Architecture

Notification subscriptions (both push and pull) are stored in memory on the Client Access server (CAS). In the case of push notifications, when a subscription comes in, the CAS begins to poll the Mailbox server every couple of seconds for new events. If any events have occurred since the last poll, the Mailbox server responds to the CAS with notifications about the events and the associated watermarks. The CAS then filters these events according to the information that is provided in the subscription, and creates a notification response that is populated with those events. Along with the events, the Client Access server appends the watermark of each event, as well as the “previous” watermark – the watermark of the last event of the previous message (the Mailbox server maintains the watermarks and updates them as events occur). Finally, the CAS sends this message to the client.

Ordering of Events

We are frequently asked – are notifications guaranteed to arrive in the order in which the events happened? The answer is yes! When the CAS sends a notifications message to the client application, the client must reply with either an “OK” or an “Unsubscribe” response. Until the CAS receives an “OK” response, it will not send out any more NEW notifications messages (even if new events occur). It will, however, go into a retry mode, if it doesn’t receive a response within the timeout amount of time, which is set on the subscription request (this is the topic of the next section). Thus, no new notifications message will be sent out by the CAS until the previous one has been acknowledged by the server. This guarantees that the order is preserved.

Timeouts

We are also often asked how push notifications timeouts work. Suppose your client subscribed to push notifications, and then unexpectedly goes offline. The server will not be able to push out the next set of events as notifications to the client (or, more importantly, the server will not get a response to its notifications message). Rather than give up right away, the server will retry to push them out up to three times. After the first failure, the server will wait the timeout amount of time (that’s the timeout that you set in the subscription request) and try again. If that attempt fails, the server will wait twice the timeout time and try again. If that fails, the server will wait three times the timeout time and try again. Finally, if the third retry attempt fails, the server will give up and delete the subscription. There is no Web service method to check on the life of the subscription, but the CAS sends StatusEvent messages every timeout amount of time, so if you don’t get a StatusEvent message within the specified time, you can assume that the subscription was deleted.

If your client application goes offline for long enough, such that the CAS went through its retry procedure and deleted the subscription, it is still possible (in almost all cases; see the next section for clarification) for your client to receive notifications that happened since the last notifications message that the client processed. To do this, you must issue a subscribe request and pass in the watermark from the point where you want to get notifications. Most of the time, you will want to pass in the last watermark seen (thus we recommend you keep track of it).

In summary, there are really two ways to end a subscription on a CAS:

You can send “Unsubscribe” in the response message (as a response to a notifications message from the CAS).
You can become unresponsive to notifications messages.

We recommend the first method (sending an unsubscribe message) rather than the second method, which causes the Client Access server to perform unnecessary work.

Reliability

Reliability of notifications is another area of confusion. Notifications are reliable – that is, all events for a mailbox that happen on the back end can be seen by the client, unless the backend server goes down. A client can always re-subscribe with the last watermark (a thing to keep in mind here: watermarks are good for about 30 days, after which they expire) and in this way get any potential events that have happened since that last watermark. The one exception to this is mailbox moves. Remember that watermarks are unique to mailbox databases, and only the Mailbox server that the watermark came from knows about that watermark. In the case of a mailbox move to another server, after the mailbox is moved, the original server notifies the CAS that no more events for that mailbox will occur, and the CAS deletes any subscriptions for that mailbox. Prior to deleting the subscriptions, the CAS will send a failure message to the client application, thus notifying it that the subscription will be deleted. The client application may now try to re-subscribe with the latest watermark. However, because the mailbox is now on another server, the previous watermarks are no longer valid (sending a subscription that includes an invalid watermark will result in an error returned by the server). Therefore, the client will have to create a new subscription from that point on. This means that any events that happened to that mailbox between the mailbox move and the creation of the new subscription creation will not be delivered.