2019
Your Guide to Integrating With Microsoft Exchange
EAS, EWS, and Graph About Nylas
Nylas is a developer platform that powers applications with email, calendar, and contacts integrations through a REST API. The Nylas API handles more than 100 million API requests per day and has synced more than 15 billion emails. 24,000 developers are signed up to use the API. We’re excited to share some of our learnings here.
Overview
While Exchange is billed as “email for enterprise”, it does, in fact, drive most business motions: internal and external email communications, calendar invites for meetings and interviews, and contacts databases. It makes sense then that many software applications are building two-way sync between their apps and user’s Exchange accounts.
In Exchange’s 20+ year history, Microsoft has created numerous APIs — but with each new API comes a surge in ongoing maintenance and support as developers are forced to rip out the old protocols and implement the new ones.
In this guide, we’ll dive into the three most commonly used protocols for integrating with Exchange:
1 EAS (ActiveSync)
2 EWS (Web Services)
3 Microsoft Graph
4 A better way to integrate with Exchange
2 EAS/ActiveSync EWS/Web Services Microsoft Graph
How it’s used Mobile API for MS Exchange API for Office 365 synchronization intended for desktop/ protocol for mail, server applications calendar, contacts, & tasks
Released 2002 2007 2015
SDK Support
Precursors MAPI MAPI, WebDAV, EWS and other ActiveSync individual Office APIs
On-prem Experimental support support for hybrid deployments
Message format Binary-encoded XML XML SOAP JSON REST over HTTP
Data Mail/calendar/ All of the Above All of the above contacts/tasks/notes + metadata and configuration (e.g. Inbox Rules). Deeper data fields (e.g. IsTeamTask)
Additional Push notifications, Rich search, access Missing some functionality simple string to public folders & functionality and searching, and device drafts, impersonation, features are in flux management many “advanced” due to the product’s services like free/ nascent nature busy, working hours
3 EAS (ActiveSync)
EAS, literally “Exchange ActiveSync Services”, was introduced in Exchange 2003 to specifically sync Exchange with mobile clients (high-latency, low- bandwidth connections). It was very innovative at the time and introduced a lightweight, idempotent procedure for data synchronization.
ActiveSync is broadly deployed and supported natively by iOS and Android. In practice, it remains the lowest common denominator for integrating applications with different versions of Exchange. Unfortunately, being a licensed technology, there is no public SDK for ActiveSync. Clients wishing to use it must implement the protocol from spec.
ActiveSync is a proprietary binary protocol, which makes it way harder to interoperate with than SOAP or XML-RPC. An ActiveSync sync loop is typically done in three phases:
1. An autodiscovery phase which translates the mailbox address to an ActiveSync endpoint
2. An explicit provisioning step which negotiates the client’s capabilities with the server’s access policies (this step takes place just once)
3. A recursive folder synchronization procedure. Messages are encoded into something called WBXML - a binarized format not unlike BSON or protocol buffers which defines a state machine and walks through it via a token stream.
In the recursive folder procedure, each token represents either a unit of data (“inline string”) or a transition (“inline string follows”). Outside of the message body, a number of Exchange-specific headers must be added to the HTTP messages. ActiveSync can run over SSL and can authenticate via OAuth or NTLM.
Nylas connects your app to Exchange in just a few lines of code. Try it out today! 4 Example of a decoded ActiveSync message
Note the use of a sync key to represent the current/next page of results.
Request:
Response:
Nylas connects your app to Exchange in just a few lines of code. Try it out today! 5 ”Jason Doe” <[email protected]>
Provisioning phase
Source: Microsoft
Nylas connects your app to Exchange in just a few lines of code. Try it out today! 6 Synchronization phase
Source: Microsoft
Nylas connects your app to Exchange in just a few lines of code. Try it out today! 7 Though ActiveSync succeeded at syncing mobile clients, it was built for mobile phones of the early 2000s. Missing functionality was spread across MAPI-over-HTTP and WebDAV.
Exchange Web Services (EWS) was introduced by Exchange Server 2007 to address the scattered landscape.
EWS (Web Services)
EWS is a much more typical XML SOAP service, replete with all the structural formalities and WS-Addressing that you would expect. Unlike ActiveSync, it does not have a provisioning phase to enforce mobile device policies.
EWS-aware applications are typically enabled individually (or as a group) by the Exchange administrator. This means that the authentication procedure is done more or less transparently through the SDK by providing a user’s credentials. Like ActiveSync, EWS also supports SSL, OAuth, and NTLM.
Example of an EWS mail sync message
Like ActiveSync, requests and responses trade a state key. EWS also uses a ChangeKey to represent the current version of an item.
Request:
Nylas connects your app to Exchange in just a few lines of code. Try it out today! 8
Response:
Nylas connects your app to Exchange in just a few lines of code. Try it out today! 9
EWS mail synchronization for Office 365
Source: Microsoft
Nylas connects your app to Exchange in just a few lines of code. Try it out today! 10 Microsoft Graph
Microsoft Graph is a fairly new service meant to unify all Office APIs (like Excel and OneDrive) and has officially preempted EWS. Therefore, Graph’s schema is organized not by product but data type (like the Mail API, Calendar API, Notifications API, etc.). This represents a convenient abstraction over the inner workings of Outlook and Excel but represents a major migration from the EWS API.
It should also be noted that not all features have been ported over - for example, [free/busy] is still in beta. Also, Graph cannot be used with on-premise deployments of Exchange. Support for hybrid deployments is currently in beta.
With Graph, authentication is typically done via OAuth and is segmented into scopes with access tokens. Being an Exchange 365 product, applications must register via the Azure active directory service, as opposed to with Exchange itself.
Example of a Graph mail call
https://graph.microsoft.com/v1.0/me/messages
{ “@odata.context”: “https://graph.microsoft.com/ v1.0/$metadata#users(‘48d31887-5fad-4d73-a9f5-3c356e68a038’)/ messages”, “@odata.nextLink”: “https://graph.microsoft.com/v1.0/me/ messages?$skip=12”, “value”: [ { “@odata.etag”: “W/\”CQAAABYAAAAiIsqMbYjsT5e/ T7KzowPTAAEMTBu8\””, ... “sender”: { “emailAddress”: { “name”: “MyAnalytics”, “address”: “[email protected]” }
Nylas connects your app to Exchange in just a few lines of code. Try it out today! 11 }, “from”: { “emailAddress”: { “name”: “MyAnalytics”, “address”: “[email protected]” } }, ...
A Better Way to Integrate With the Microsoft Exchange API
Integrating with EAS takes anywhere from 12-18 months, and the ongoing maintenance and support costs increase over time as your platform scales.
We built the Nylas Email API to provide a simpler way to integrate with the Exchange, Gmail, Outlook, and every other email provider in the world. With Nylas, you can build full CRUD and bi-directional sync between your app and 100% of email service providers in the world.
Nylas SDKs for Exchange ActiveSync
The Nylas API is built for developers first. We support three major SDK languages to help make your EAS integration as simple as possible.
Try the Nylas API today – create an account and sync up to 10 accounts for free here!
Nylas connects your app to Exchange in just a few lines of code. Try it out today! 12 Nylas.com Github.com/Nylas @Nylas