An Activesync Primer – The Options request

Now that my app is out in the market (finally), I think it is time to write a brief how-to on ActiveSync and how I managed to get things working.

First off, I would like to acknowledge the help and support from the following individuals / websites, without  whom this app would not been possible

• Andreas – Digging into the Exchange protocol
• Exchange Server Protocol Documents
• k9mail

Ok lets get started.

The Activesync OPTIONS Command

This is the first command that you want to send to an ActiveSync server. If the message is correctly formatted, the server responds with with a list of commands supported, and also the ActiveSync version that is supported. Here is a sample request (RAW view from Fiddler). Please note that the text in bold will need to be modified, and actual values will need to be inserted. See comments prefixed by // for a better description of each field.

[EDIT 01/20/2011] Turns out if you are connecting to Google Apps (that runs on Linux) or an Exchange server that is protected by a reverse proxy, case matters. so the Activesync text below should be ActiveSync (note the camelcase)
// Send an Option request to the mail server. Append the
// following location to the URL Microsoft-Server-ActiveSsync
// and add the username used to log into the server.
OPTIONS https:/ /mail.example.com/Microsoft-Server-ActiveSsync?User=username HTTP/1.1

// Set this to anything. Since I wrote an Android app,
// I set this to Android
User-Agent: Android

// This is the text Basic followed by a
// base64 encode of the string DOMAIN\USERNAME:PASSWORD.
// Replace with appropriate values.
Authorization: Basic RE9NQUlOXFVTRVJOQU1FOlBBU1NXT1JE

[EDIT 01/20/2011] Exchange server 2010 does not like it if you send any additional headers. The only required headers are the auth and the user-agent. Hence none of the headers below are required for the OPTIONS request
// Since this is an Options request, there is no content
// just the headers. Hence this is set to zero
Content-Length: 0

// Indicate to the Exchange server that we are sending
// WBXML encoded content.
// Right now since is not really applicable.
Content-Type: application/vnd.ms-sync.wbxml

// Identifies the protocol version the client (we) support
MS-ASProtocolVersion: 12.1

// English language
Accept-Language: en-US

// Hostname the request is being sent to
Host: mail.example.com

If all goes well, you should get a response that looks somewhat like this

HTTP/1.1 200 OK
Cache-Control: private
Allow: OPTIONS,POST
Content-Length: 0
Server: Microsoft-IIS/7.5
MS-Server-ActiveSync: 8.3
MS-ASProtocolVersions: 1.0,2.0,2.1,2.5,12.0,12.1
MS-ASProtocolCommands: Sync, SendMail, SmartForward, SmartReply, GetAttachment, GetHierarchy, CreateCollection, DeleteCollection, MoveCollection, FolderSync, FolderCreate, FolderDelete, FolderUpdate, MoveItems, GetItemEstimate, MeetingResponse, Search, Settings, Ping, ItemOperations, Provision, ResolveRecipients, ValidateCert
Public: OPTIONS,POST
X-AspNet-Version: 2.0.50727
X-Powered-By: ASP.NET
Date: Mon, 06 Dec 2010 21:14:17 GMT

The 200 response code indicates a success. The MS-ASProtocolVersions field indicates the version of the Activesync Protocol that is supported by the server. The MS-ASProtocolCommands field indicates what Activesync commands are supported by the server.

I will keep updating my blog with more information on how to use Activesync to query the GAL. Stay tuned.