How do you use the new Exchange documentation?

Photo by Curious Yellow

Yesterday, 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 like Moonrug’s, that would open the door to a lot of innovative new products.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: