Exchange Protocols Overview Andrew Davidoff Senior Software Engineer Microsoft Corporation

Agenda Brief introduction to Exchange Server Open Specifications An overview of the protocol architecture for Exchange Important protocol families that are used to communicate with Exchange Server

Introduction to Open Specifications Normative language Designed to document bits over the wire No APIs – only Protocols Normative and informative content Follows RFC 2119 MUST, SHOULD, MAY are used to document version-specific behavior Strict document structure Windows/Exchange or product API knowledge not required… Microsoft Products are not mentioned in normative content, only in endnotes We are striving to make our Open Specifications complete, accurate and implementable

Exchange Protocols

Overview Document [MS-OXPROTO] Defines Exchange protocol families Informative and Scenario-Based How multiple protocols work together in typical scenarios How to complete the same task using different protocol families Walkthroughs and examples Send email via RPC/ROPs, EWS, or Exchange ActiveSync Resolve a recipient from an Address Book Synchronize items Provision mobile client using Exchange ActiveSync Many other scenarios

Protocol families Remote Operations (a.k.a. RPC) Exchange Web Services (EWS) Exchange ActiveSync (EAS) Other groups of protocols Autodiscover Name Service Provider Interface (NSPI) Content Conversion Standards Support

Client communication with Exchange Exchange Server Smartphone/Tablet EAS Storage EWS Mailbox store Outlook for MAC Public store RPC/ROPs OAB Non-Exchange SMTP NSPI Outlook for Windows Desktop Auto-Discover Exchange SMTP POP/IMAP SMTP POP/IMAP Client

Exchange RPC/ROPs protocols Implemented in some form from “Day 1” (such as Exchange 4.0), extended and re-architected several times Low-level access to Exchange Storage Workhorse for Outlook communication with Exchange Used by MAPI Transport layer: ROPs (Remote Operations) within an RPC binary blob Optimized to minimize traffic on the wire; very complex parsing RPC can use HTTP(S) or TCP connections (HTTP(S) only in Exchange 2013) New [MS-OXCMAPIHTTP] as alternative to use ROPs over HTTP; no RPCs

Exchange RPC/ROPs: Transport Header Binary Blob (EcDoRpcExt2) RopSize ROP1 ROP2 … HSOT Table RopID ROP Data RopID ROP Data Note: No ROP Data size or end marker. Every ROP Data in the blob must be parsed. Every RopID has different ROP Data structure. Number of documented RopIDs: 130

RPC/ROPS protocols - continued RPC/ROPs protocols define both Exchange (server) and Outlook (client) behaviors Client is handling most of low-level processing and logic behind complex items – messages, folders, calendar items, contacts, tasks, etc. Naming: [MS-OXO*] and [MS-OXC*] (few exceptions) 40+ Protocols, ~3000 pages

Exchange Web Services (EWS) Alternative to RPC protocols Higher level of abstraction compared with RPC protocols In Exchange RPC world, it is the responsibility of the client to implement tasks, contacts, calendars, etc. EWS (and EAS) implement them on server side in a way that is interoperable with Outlook. First implemented in Exchange Server 2007 Outlook uses subset of EWS protocols Unified Messaging, MailTips, Availability, OOF, Office Apps, Room List, Archive, Mailbox Policies, Calendar Sharing, Site Mailboxes, etc. New Exchange features tend to be implemented in EWS

Exchange Web Services (EWS) - continued Lync/Skype and SharePoint use several EWS protocols to communicate with Exchange Server Outlook for Mac is built on EWS Mac OSX Snow Leopard has EWS support via Apple’s Mail application Exchange LOB applications should use EWS Transport: Naming: [MS-OXW*] 43 Protocols, ~2000 pages SOAP HTTP/HTTPS

Exchange ActiveSync (EAS) High level of abstraction, similar to EWS in complexity, limited set of objects and features Designed to be used by smartphones and handhelds Industry standard, several non-Exchange Server implementations Wide range of clients – Windows 8, iOS, Android, … even Outlook to Hotmail Transport: Naming: [MS-AS*] 15 Protocols, ~900 pages WBXML HTTP/HTTPS

Other Exchange protocols NSPI (Address Book) Directory/Profile Services (Autodiscover) Content Conversion, how Internet (RFC-based) content gets converted to Exchange objects and back Standards-based protocols – Extensions and Compliance [MS-OXPROTO] is a good reference Exchange WebDAV protocols – deprecated

Exchange test tools update New parsers for Message Analyzer Protocol families: EAS, EWS, RPC, and MAPIHTTP Retirement of Exchange RPC Extractor (RPX) New test suites for EAS, EWS, RPC, and MAPIHTTP

Summary Many options are available when developing with Exchange protocols; choose the protocol family carefully. There are a lot of resources to assist with your development (most are free) that you can take advantage of. Many interoperability tools (test suites, parsers, etc.) are already available.

Exchange protocols resources All Exchange protocol documents https://msdn.microsoft.com/en-us/library/cc425499(v=exchg.80).aspx Microsoft Message Analyzer http://www.microsoft.com/en-us/download/details.aspx?id=44226 Protocol Test Suites https://connect.microsoft.com/site216/Downloads Help with Open Specifications: mailto:dochelp@microsoft.com Office Interoperability blog: http://blogs.msdn.com/b/officeinteroperability/

Mail, Calendar, and Contacts REST APIs Andrew Davidoff Senior Software Engineer Microsoft Corporation

Why use REST APIs? Hundreds of millions of Users Office 365, Outlook.com; hybrid and on-premises on the roadmap Powerful, easy, and intuitive way to access and manipulate Office 365 data Granular, tightly scoped permissions to access user data Based on open standards – OAuth 2.0, JSON, ODATA v4.0 Web-friendly APIs to enable web and mobile applications developers

What do the REST APIs in Office 365 offer? Active Directory Exchange & Outlook.com SharePoint Sites OneDrive Mail Users OneDrive for Business Calendar Client API Contacts Groups Sites, Lists and Libs Search O365 Groups Workflow …

Common Consent Framework Single Authentication flow for O365 Azure AD Graph, Exchange, SharePoint Device apps and web apps Admin and end-user consent Secure protocol OAuth 2.0 authorization No capturing of user credentials Fine-grained access scopes Supports multi-factor authentication (MFA) and federated user sign-in Long-term access through refresh tokens

Discovering endpoints and APIs Office 365 discovery services Rich service metadata Lists all entities, collections, actions, complex types, enumerations and their properties For example: https://outlook.office365.com/api/v1.0/$metadata

Rich tooling .NET SDK to build many types of apps using Visual Studio .NET Windows Store Apps Windows Forms Applications WPF Applications ASP.NET MVC Web Applications ASP.NET Web Forms Applications Xamarin Android and iOS Applications Multi-device Hybrid Apps (Cordova) Android and iOS SDKs

You’ve got mail! Permissions Entities, Collections, Actions Samples Read, Read+Write, Send Entities, Collections, Actions Samples https://outlook.office365.com/api/v1.0/Me/Folders/Inbox https://outlook.office365.com/api/v1.0/Me/Folders/Inbox/Messages?$top=1 https://outlook.office365.com/api/v1.0/Me/SendMail/ Entity Collection Actions Folder Folders CRUD, Copy, Move Message Messages CRUD, Copy, Move, Reply, ReplyAll, Forward, Send, CreateReply, CreateReplyAll, CreateForward  Attachment Attachments CRUD Entity Collection Intuitive Send API

No client-side recurrence expansion required Calendar – Coffee @ 4? Permissions Read, Read+Write Entities, Collections, Actions Samples https://outlook.office365.com/api/v1.0/Me/Calendar https://outlook.office365.com/api/v1.0/Me/Calendar/Events?$top=1 https://outlook.office365.com/api/v1.0/Me/CalendarView?startDateTime=2015-05-01 & endDateTime=2015-05-31 Entity Collection Actions CalendarGroup CalendarGroups CRUD  Calendar Calendars Event Events CRUD, Accept, Decline, TentativelyAccept CalendarView N/A Read Attachment Attachments CRUD No client-side recurrence expansion required Entity Collection

Contacts – Your number again? Permissions Read, Read+Write Entities, Collections, Actions Samples https://outlook.office365.com/api/v1.0/Me/ContactFolders/ https://outlook.office365.com/api/v1.0/Me/Contacts/ Use Azure Active Directory API to find users in an O365 organization (tenant) Entity Collection Actions ContactFolder ContactFolders CRUD Contact Contacts

Demo Sample REST API Requests

Rich query syntax using OData Scenario URL Get 5 messages from Inbox https://outlook.office365.com/api/v1.0/Me/Folders/Inbox/Messages?$top=5 Get the next 10 messages https://outlook.office365.com/api/v1.0/Me/Folders/Inbox/Messages?$top=10&$skip=5 Get top 10 messages sorted by DateTimeReceived https://outlook.office365.com/api/v1.0/Me/Folders/Inbox/Messages?$top=10&$orderby=DateTimeReceived Get selective properties on messages https://outlook.office365.com/api/v1.0/Me/Folders/Inbox/Messages?$top=5&$select=From,DateTimeCreated,Subject Get events starting after a particular DateTime https://outlook.office365.com/api/v1.0/Me/Events?$top=5&$select=Subject,Start,End&$filter=Start ge 2015-10-19T20:00:00Z Get calendar view for a week with selected properties, latest events first https://outlook.office365.com/api/v1.0/me/calendarview?startDateTime=2015-03-26T00:00:00Z&endDateTime=2015-10-19T00:00:00Z&$select=Subject,Start,End&$orderby=Start Get # of messages with attachment(s) https://outlook.office365.com/api/v1.0/Me/Folders/Inbox/Messages/$count?$filter=HasAttachments eq true Get count and selected props on messages with attachment(s) https://outlook.office365.com/api/v1.0/Me/Folders/Inbox/Messages?$format=application/json;odata.metadata=none&$select=Subject&$filter=HasAttachments%20eq%20true&$count=true Get contact with a given name https://outlook.office365.com/api/v1.0/Me/Contacts/?$filter=Givenname eq 'John'

Roadmap Enable end-to-end scenarios – with focus on web and mobile applications Notifications Custom/Extended properties Sync Free/Busy Mail tips, OOF settings Delegate scenarios On-premises Exchange Server 2016 support for REST APIs is coming Support for Exchange Server 2013 is on the roadmap as well Outlook.com accounts can be accessed by REST APIs Different endpoint, same principles New Unified (Graph) APIs coming very soon The same REST APIs to access Exchange, SharePoint, Active Directory, and One Drive for Business data Perfect for complex workflow-based solutions

Code samples on GitHub Plenty of sample code on GitHub MailSim tool now supports REST APIs https://github.com/OfficeDev/Interop-MailSim Two implementations: using SDK or direct HTTPS Includes code that does Authentication (OAuth2) in both implementations More Open Source Applications are in the works

http://dev.office.com REST API Resources Sign up Explore Training http://dev.office.com/getting-started Explore http://apisandbox.msdn.microsoft.com Training http://dev.office.com/training API endpoints for China https://msdn.microsoft.com/office/office365/APi/o365-china-endpoints

Questions?