1. EWS Overview Tom Jebo Microsoft Open Specifications

2. Agenda What is EWS? Protocol Overview Autodiscover EWS Versioning EWS Operations Using EWS APIs Demo Resources and Tools

3. What is EWS? HTTP/SOAP based interface to Exchange Mailboxes EWS conversations require: HTTP GET/POST XML/SOAP When to use EWS? Alternative to MAPI (RPC or RPC/HTTP), intuitive/readable XML Email clients, admin functions, applications, web apps/services, e-Discovery. Benefits? Extensive command set and functionality access Includes modification of items Web-based (cross domains)

4. Clients Outlook OOF and Availability and new features Outlook for Mac (exclusively) Others: eM Thunderbird

5. Exchange and Protocol Versions Exchange support for EWS Started support in Exchange 2007 Previously in Exchange 2003, WebDAV was slower syncing. Currently support in Exchange 2013 as well as Exchange Online Protocol versions Versioned by schema for the SOAP bodies RequestServerVersion header element in each request Next slides for details…

6. Schema versions Archiving eDiscovery Personas Retention policies Unified Contact Store User photos Full access to items, folders, and attachments (Create, Get, Update, Delete) Availability Out of Office settings Notifications Synchronization Name resolution Distribution list (DL) expansion Search

7. RequestServerVersion header element <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">

8. ServerVersionInfo header element <h:ServerVersionInfo MajorVersion="15“ MinorVersion="1“ MajorBuildNumber="286“ MinorBuildNumber="24“ Version="V2_66" xmlns:h="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"/> <m:GetRoomListsResponse ResponseClass="Success" xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" … NoError

9. Schema versioning on a server Always messages.xsd and types.xsd in the virtual directory New version: Rename old version and include in new files with the base names CUs (rollups) now have EWS schema updates for Exchange Online. Schema file and version names are updated with SPs and releases in on-prem.

10. services.wsd l messages.x sd types.xsd For example, use svcutil.exe to generate code based on WSDL.

11. EWS Protocol Overview

12. EWS in Exchange Exchange Web Services in relation to the other protocols used by Exchange MS-OXPROTO 2.1

13. The Web Services Open Specifications for Exchange [MS-OXWSADISC] [MS-OXWSCDATA] [MS-OXWSXPROP] [MS-OXWSCORE] [MS-OXWSMSG] [MS-OXWSFOLD] [MS-OXWSCONT] [MS-OXWSMTGS] Etc.. [MS-OXPROTO] 2.2.10 Types and Properties Operations on various items Configuration settings

14. Where to start? Autodiscover! What is it? Finds a URL for EWS calls Uses SMTP address and password Why use it? Topologies change, mailboxes move, URLs become outdated EWS fails (CAS) wrong URLs Alternative: hard code URLs MS-OXDISCO MS-OXDISCLI LDAP and DNS

15. What is the process? LDAP/DNS Finding an Autodiscover Server Autodiscover Finding an EWS URL EWS conversation Assumption: trustworthy Autodiscover URL (credentials sent) – HTTPS and valid certificate. Querying LDAP (serviceBindingInformation), DNS SRV (_service/_port), or HTTP redirection to find an autodiscover server. [MS-OXDISCO] 3.1.5 has an overview. Query the Autodiscover server for a service endpoint (aka EWS server URL) to use. [MS-OXDSCLI] describes simple XML query like: http:// /Autodiscover/Autodiscover.xml and https://Autodiscover. /Autodiscover/Autodiscover.xml. [MS-OXWSADISC] describes SOAP-based query to URLs like: https://autodiscover. /autodiscover/autodiscover.svc https:// /autodiscover/autodiscover.svc Finally, talk to the EWS server to authenticate the user and issue commands

16. Autodiscover example tomjebo@Service.microsoft.com http://schemas.microsoft.com /exchange/autodiscover/outlook/responseschema/2006a

17. Autodiscover response example Tom Jebo /o=ExchangeLabs/ou=Exchange Administrative Group (FYDIBOHF23SPDLT)/cn=Recipients/cn=microsoft.onmicrosoft.com-55760-Tom Jebo tomjebo@microsoft.com e7908b08-1b41-4665-ba7f-33677ce0cf32

18. email settings True False EXHTTP outlook.office365.com On Basic https://outlook.office365.com/EWS/Exchange.asmx https://outlook.office365.com/owa/ ?path=/options/callanswering

19. Tracing Autodiscover in Outlook Ctrl + Shift + Right click on the task tray icon for Outlook Then select: “Test E-mail AutoConfiguration…”

20. Functional Overview of Protocol Review several of the functional groups Example of using EWS operations follows

21. Core Items and Data Types [MS-OXWSCORE]/[MS-OXWSDATA] Defines the base item operations and base types Get, Create, Move, Update, Delete, Copy, Send … are all defined here for the general case. Extended in other specs

22. Email message operations [MS-OXWSMSG] Operations: GetItem – ItemShape: IdOnly/AllProperties CopyItem – copies to a folder id, returns new id (new item) SendItem – send created email message by item id CreateItem – specify item(s) and folder to save to MoveItem – no new id returned UpdateItem – item id, saveto id, field changes array. …

23. <RequestServerVersion Version="Exchange2012" xmlns="http://schemas.microsoft.com/exchange/services/2006/types"/> <messages:GetItem xsi:type="messages:GetItemType" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:types="http://schemas.microsoft.com/exchange/services/2006/types" xmlns:messages="http://schemas.microsoft.com/exchange/services/2006/messages"> IdOnly  [MS-OXWSCDATA] 2.2.4.38, 2.2.5.7 AAMkADQ4NzFlNGQzLTE0MjctNDY1MS04MmY xLTkzZTJjOGE3Nzg5MQBGAAAAAACFZkYb4gNeRoKFg0vNFMECBwAR7Z LzvL8SS65OYqkrzuiyAAADWe9NAAC5/m6giL4oQqROGz5xBYbaAAJnUhTYAAA= [MS-OXWSCORE] Core Items Core Items Web Service Protocol

24. Folder operations [MS-OXWSFOLD] Operations: GetFolder – folder id and shape: properties CreateFolder – new child folder DeleteFolder – non-default folders EmptyFolder – deletes contained items & subfolders MoveFolder – everything moves with the folder … you get the idea! FolderId or DistinguishedFolderId [MS-OXWSCDATA] 2.2.4.23 has the names enum “inbox” “contacts” “tasks” etc…

25. Appointments/Meetings and Contacts [MS-OXWSMTGS] and [MS- OXWSCONT] Operations: CopyItem UpdateItem CreateItem DeleteItem GetItem MoveItem Different semantics and properties for these but the same operations. CalendarItemTyp e ContactItemType

26. Searching for Folders and Items [MS-OXWSSRCH] Operations: FindFolder – get a list of subfolders based on “Restriction” FindItem – get an item in a folder(s) by Example on next slide…

27. AllProperties

28. NoError IPF.Note _tom … 23191 8 0 …

29. Data Xfer and Sync [MS-OXWSBTRF] ExportItems UploadItems <xs:element name="Data" type="xs:base64Bina ry " [MS-OXWSSYNC] SyncFolderHierarchy SyncFolderId

30. Availability operations [MS-OXWAVLS] GetUserAvailability – list of mailboxes to query free/busy options to query mtg suggestions options: max non-work hours results meeting duration etc…

31. <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"> urn:uuid:4BA16712-80B3-4B63-8EAE-C224FE79D8D9 … tomjebo@microsoft.com Organizer … [MS-OXWSAVLS] Availability Web Service Protocol

32. … 2015-09-27T00:00:00 2015-11-08T00:00:00 30 MergedOnly 30 Poor 2015-09-27T00:00:00 2015-11-08T00:00:00

33. DEMO: Example requests and responses Use EWSEditor to craft raw HTTP requests which would be called by the client. Then show these as examples. Let’s look at just a few examples for common requests like: 1.Finding folders 2.Getting mail items in a folder 3.Get a calendar appointment 4.Look up a contact

34. EWS Managed API

35. Overview of the API (just highlights) https://github.com/OfficeDev/ews-managed-api And Microsoft download API version 2.5 Requires.Net/C# or VB

36. DEMO:EWS Managed API in code example Take a look at some code examples using EWS Managed API.

37. javascript EWS in js (mail add-in only): https://msdn.microsoft.com/en-us/library/office/fp161019.aspx Mailbox.makeEwsRequestAsync Only available in Outlook or mail add-ins General javascript apps: XmlHttpRequest object allows calls for raw HTTP POSTS Supported in many web browsers including IE General js code

38. Tools

39. EWSEditor This is your friend! Download: http://ewseditor.codeplex.com http://ewseditor.codeplex.com Log viewer Autodiscover viewer EWS POST

40. Message Analyzer Download free EWS Parsers: Tools | Asset Manager… search on Exchange Web Services Version 1.1 (January 2015) Demo: capture autodiscover, GetItem, FindItem

41. Fiddler Decrypts for you No parser Only shows HTTP(S) traffic HTTP/SOAP packets Demo with EWSEditor, Outlook, etc…

42. Netmon Parsers available Need unencrypted traffic using server cert Replaced by Message Analyzer Download and parsers: http://blogs.technet.com/b/netmo n/p/downloads.aspx Support and discussion: https://social.technet.microsoft.co m/Forums/en- US/home?forum=netmon

43. References and resources

44. EWSEditor download http://ewseditor.codeplex.com Message Analyzer http://www.microsoft.com/en-us/download/details.aspx?id=44226 Fiddler http://www.telerik.com/download/fiddler EWS client design overview for Exchange https://msdn.microsoft.com/en-us/library/office/jj190904(v=exchg.150).aspx Exchange EWS Test Suites http://connect.microsoft.com/site216/Downloads/DownloadDetails.aspx?DownloadID=4 6994