Microsoft released a new series of their Open Specification documents, many of them related to Exchange and email. There are in-depth descriptions of all the APIs and protocols that connect the various parts of the mail ecosystem together, so it’s essential reading for anyone working in the Exchange ecosystem. When you first start looking through them, it’s rather opaque, using a lot of internal code names and DOS-style filenames like [MS-OXCFOLD].pdf, so here’s some tips I found handy.
First, download the whole Exchange archive of documents as a zip file. You’ll be doing a lot of referring back and forth between specifications, and that’s a lot easier when they’re local files.
Second, bookmark the official Exchange specification forum, or subscribe to its RSS feed. Microsoft have traditionally been very good at supporting developers, and they’re active answering questions here. It’s useful both if you end up with your own queries, and to learn from what other people are hitting.
Now the tricky part is understanding what documents to look at. There’s a few conventions in the file names that help. They all start with MS-OX, but the next letter sometimes gives an idea of what category the file covers. C stands for communication protocols, O for object definitions, so MS-OXCMSG covers how to transmit a message between machines, and MS-OXOMSG defines the properties of an email object. Interestingly, MS-OXMSG has all the details of the .msg file format, though there’s already some information available on it from reverse engineering.
I didn’t find the main MS-OXDOCO file that was supposed to explain what was included very useful. The MS-OXPROTO overview was a useful description of the overall architecture, but didn’t give me much of a clue where to start either. Since I was especially interested in the Outlook Exchange Transport Protocol (formerly known as MAPI/RPC), I started by examining the MS-OXCMSG message communication document.
Like most API documentation, it’s pretty dry and detailed, but I find the best place to start is actually at the end, by looking through the examples. These don’t have any code unfortunately, but they are pretty good at taking you through the steps of doing something useful with the protocols. It’s also a good idea to look closely at the references to other protocols in each document, since most of them work by building on top of other APIs. For the message transport, the key underlying protocol is Microsoft’s remote operation API, or ROP, defined in MS-OXCROP.
All-in-all, this new release of information looks like good news for anyone who has to make their product work with Exchange. You’ll still need a lot of patience and some packet sniffing tools, but this makes implementing your own services that replace parts of the mail ecosystem a lot less daunting. I’m also hoping this helps the development of interoperability libraries , that would open the door to a lot of innovative new products.
There are three elements to this:
- Detailed documentation of MAPI. This is a very rich set of APIs for accessing Outlook information: emails, calendar items, directory entries, etc.
- Detailed documentation on how to write MAPI service providers. This lets third parties offer their services, and be accessible via MAPI calls. In addition, Microsoft sells licenses to write such service providers. We understand the fees are very modest.
- Detailed documentation on how to encapsulate MAPI in an on-the-wire protocol (aka MAPI/RPC).
Fifteen years ago:
- Documentation for MAPI was available, if you knew whom to ask. It was very long, indescribably boring (like most API documentation), and rather incomplete (because of the complexity of fully modeling the messaging environment).
- Documentation for the service provider interface was also available. Like fine French lingerie, it was incredibly skimpy.
- Documentation for MAPI/RPC wasn’t ever published.
Our overall sense of what has happened is this:
- MAPI and service provider documentation was allowed to whither, and was withdrawn.
- It was resurrected in response to a mandate from the European Commission, but most people still found it unhelpful.
- Now Microsoft is applying proper resources to maintain the documentation and interfaces.
All in all, a good development–it’s good that MAPI and its service provider interfaces should be well documented and supported.