Your Guide to Integrating with Microsoft Exchange
Total Page:16
File Type:pdf, Size:1020Kb
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: <?xml version=”1.0” encoding=”utf-8”?> <airsync:Sync xmlns:airsync=”AirSync”> <airsync:Collections> <airsync:Collection> <airsync:SyncKey>866776076</airsync:SyncKey> <airsync:CollectionId>7</airsync:CollectionId> <airsync:ConversationMode>1</airsync:ConversationMode> <airsync:Options> <airsyncbase:BodyPreference xmlns:airsyncbase=”AirSyncBase”> <airsyncbase:Type>2</airsyncbase:Type> <airsyncbase:TruncationSize>500</ airsyncbase:TruncationSize> <airsyncbase:Preview>100</airsyncbase:Preview> </airsyncbase:BodyPreference> </airsync:Options> </airsync:Collection> </airsync:Collections> <airsync:HeartbeatInterval>60</airsync:HeartbeatInterval> </airsync:Sync> Response: <?xml version=”1.0” encoding=”utf-8”?> <Sync xmlns=”AirSync” xmlns:email=”E m ail” xmlns:airsyncbase=”AirSyncBase” xmlns: email2=”Email2”> <Collections> <Collection> <SyncKey>1992475662</SyncKey> <CollectionId>7</CollectionId> <Status>1</Status> <Commands> <Add> <ServerId>7:1</ServerId> <ApplicationData> <email:To> Nylas connects your app to Exchange in just a few lines of code. Try it out today! 5 ”Jason Doe” <[email protected]> </email:To> <email:From> ”Albert Einstein” <[email protected]> </email:From> <email:Subject>Test Mail</email:Subject> 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: <?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=”Exchange2010_SP2” /> </soap:Header> Nylas connects your app to Exchange in just a few lines of code. Try it out today! 8 <soap:Body> <m:SyncFolderItems> <m:Ite m Shape> <t:BaseShape>AllProperties</t:BaseShape> </m:Ite m Shape> <m:SyncFolderId> <t:DistinguishedFolderId Id=”inbox” /> </m:SyncFolderId> <m:SyncState>H4sIAAA==</m:SyncState> <m:MaxChangesReturned>10</m:MaxChangesReturned> <m:SyncScope>NormalItems</m:SyncScope> </m:SyncFolderItems> </soap:Body> </soap:Envelope> Response: <?xml version=”1.0” encoding=”utf-8”?> <s:Envelope xmlns:s=”http://schemas.xmlsoap.org/soap/envelope/”> <s:Header> <h:ServerVersionInfo MajorVersion=”15” MinorVersion=”0” MajorBuildNumber=”731” MinorBuildNumber=”10” Version=”V2_3” xmlns:h=”http://schemas.microsoft.com/exchange/services/2006/types” xmlns=”http://schemas.microsoft.com/exchange/services/2006/types” xmlns:xsd=”http://www.w3.org/2001/XMLSchema” xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” /> </s:Header> <s:Body xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xmlns:xsd=”http://www.w3.org/2001/XMLSchema”> <m:SyncFolderItemsResponse xmlns:m=”http://schemas.microsoft.com/exchange/services/2006/ messages” xmlns:t=”http://schemas.microsoft.com/exchange/services/2006/ types”> <m:ResponseMessages> <m:SyncFolderItemsResponseMessage ResponseClass=”Success”> <m:ResponseCode>NoError</m:ResponseCode> <m:SyncState>H4sIAAAAAAAEAO29B2AcSZY==</m:SyncState> <m:IncludesLastItemInRange>true</ m:IncludesLastItemInRange> Nylas connects your app to Exchange in just a few lines of code. Try it out today! 9 <m:Changes> <t:Update> <t:Message> <t:ItemId Id=”q04QAAAA==” ChangeKey=”CQAAABYAAADZGACZQpSgSpyNkexYe2b7AAAAird/” /> <t:ParentFolderId Id=” AgENAAAA” ChangeKey=”AQAAAA==” /> <t:Ite m Class>IPM.Note</t:Ite m Class> <t:Subject>RE: Company Soccer Team</t:Subject> 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