Get Started with Exchange Web Services (EWS)

In enterprises it’s very common to develop applications that are capable of sending out emails automatically. It’s also quite common to have applications that connect to a mailbox and download emails to import them into another system.

Starting with Microsoft Exchange 2010, it’s no longer possible to use WebDAV to access an Exchange server. Now, the preferred method of communication with the server is through Exchange Web Services (EWS), which was introduced in Exchange 2007.

In the same way as WebDAV, EWS uses XML for the communication with Exchange. But unlike WebDAV, EWS implements the SOAP protocol. It defines the service’s contract in a WSDL document.

Since EWS is a normal web service, we can access Exchange from any platform. In .NET, we could simply add a web reference to our project. This would automatically generate proxy classes that we can use to communicate with EWS. These classes would allow us to send email, get email, send meeting invitations, manage contacts, etc.

Unfortunately, even with the help of these proxy classes, it can be quite complex to work with EWS.

In .NET, there’s a simpler way to access EWS than dealing with the web service through proxies. I’m talking about Exchange Web Services Managed API. This API defines .NET classes specific to work with EWS.

The EWS Managed API can downloaded from Microsoft’s Download Center.The latest version as of this post is 1.1.

After installing EWS Managed API, you’ll find a new directory at a similar location to C:\Program Files\Microsoft\Exchange\Web Services\1.1. In this directory you’ll find the Microsoft.Exchange.WebServices.dll and the Microsoft.Exchange.WebServices.xml files. Just copy these files and add them to your project directory. I usually create a folder named REF inside my project directory and place all the assemblies that the project will reference in there.

Don’t forget to reference Microsoft.Exchange.WebServices.dll from your project. You’ll also need to import the following namespace in your code.

using Microsoft.Exchange.WebServices.Data;

Before we can start interacting with the Exchange server through EWS, we need to establish a connection. We do this by creating a new instance of the ExchangeService class.

        public static ExchangeService CreateConnection(String url)
        {
            // Hook up the cert callback to prevent error if Microsoft.NET doesn't trust the server
            ServicePointManager.ServerCertificateValidationCallback =
                delegate(
                    Object obj,
                    X509Certificate certificate,
                    X509Chain chain,
                    SslPolicyErrors errors)
                {
                    return true;
                };

            ExchangeService service = new ExchangeService();
            service.Url = new Uri(url);

            service.Credentials = new NetworkCredential("username", "password", "domain");

            return service;
        }

This little helper method takes the URL where EWS is located and returns a new instance of the ExchangeService class.

Sometimes .NET will throw an error when it doesn’t trust the server because we don’t have the appropriate certificate installed. An easy way of avoiding this is to define a delegate for the ServerCertificateValidationCallback callback that always returns true.

The Exchange Web Services are usually located at a URL in this format:

http(s)://servername/EWS/Exchange.asmx

Or this one:

http(s)://autodiscover.domain/EWS/Exchange.asmx

The ExchangeService class will not try to connect to the Exchange server until we execute the first operation, like for instance sending or getting email.

Here’s a little function to send out an email using the EWS Managed API and the method we defined above.

        private void SendEmail()
        {
            ExchangeService service = CreateConnection("https://autodiscover.test.com/EWS/Exchange.asmx");

            EmailMessage msg = new EmailMessage(service);
            msg.ToRecipients.Add(new EmailAddress("oscar@test.com"));
            msg.Subject = "Test email";
            msg.Body = new MessageBody(BodyType.HTML, "<p>Hello Email!</p>");
            msg.Send();
        }

The EmailMessage class represents an email. We need to pass an instance of the ExchangeService class to its constructor since ultimately that’s what’s use to communicate with the Exchange server.

In other posts we’ll see how to do other things with Exchange EWS.