Get started with EWS client applications
Create your first application by using Exchange Web Services (EWS) in Exchange.
EWS is a comprehensive service that your applications can use to access almost all the information stored in an Exchange Online, Exchange Online as part of Office 365, or Exchange on-premises mailbox. EWS uses standard web protocols to provide access to an Exchange server; libraries like the EWS Managed API wrap the EWS operations to provide an object-oriented interface. After you've run the examples in this article, you will have a basic understanding of what you can do with EWS.
You can call EWS operations from any operating system or language, because the EWS requests and responses use the SOAP protocol. The examples in this article are written using C# and make use of the .NET Framework HttpWebRequest and HttpWebResponse objects; however, the important part of the code is the XML used to make the EWS request and the XML response returned from the server. The code examples emphasize the XML transactions and not processing the XML.
Note
We’re removing the ability to use Basic authentication in Exchange Online for EWS beginning October 2022 Deprecation of Basic authentication in Exchange Online. You should use OAuth authentication instead. Authenticate an EWS application by using OAuth
You'll need an Exchange server
If you already have an Exchange mailbox account, you can skip this step. Otherwise, you have the following options for setting up an Exchange mailbox for your first EWS application:
Get an Office 365 Developer Site(recommended). This is the quickest way for you to get an Exchange mailbox.
Download Exchange Server.
After you've verified that you can send and receive email from your Exchange server you are ready to set up your development environment. You can use Outlook Web App to verify that you can send email.
You'll also need to know the URL of the EWS endpoint for your server. In a production application, you'd use Autodiscover to determine the EWS URL. The examples in this article use the Office 365 EWS endpoint URL, https://outlook.office365.com/EWS/Exchange.asmx. The Next steps section has links to more information about Autodiscover when you're ready.
If you are testing your application using an Exchange server that has the default self-signed certificate, you'll need to create a certificate validation method that meets the security requirements of your organization.
Set up your development environment
The tools that you use to create your first EWS application depend on the operating system and language that you use, and are mostly a matter of taste. If you want to follow along with the C# examples in this article, you'll need:
- Any version of Visual Studio that supports the .NET Framework 4.0.
- An Internet connection that your development machine can use to contact your Exchange server. If you can use Outlook Web App with a DNS name rather than an IP address to connect to your Exchange server, you are set up.
Create your first EWS application
The EWS application that you will create shows two typical scenarios for using EWS:
- Get information from an Exchange mailbox and display that information to the user.
- Perform an action, such as sending an email, and check the response to see if the action succeeded.
Let's get started.
Set up the solution
First, create a new console application solution using Visual Studio. When the solution is ready, create a new object called Tracing.cs. Use this object to write information to both the console and a log file so that you can review the results after you run your code. Paste the following code into the Tracing.cs file.
using System;
using System.IO;
namespace Microsoft.Exchange.Samples.EWS
{
class Tracing
{
private static TextWriter logFileWriter = null;
public static void OpenLog(string fileName)
{
logFileWriter = new StreamWriter(fileName);
}
public static void Write(string format, params object[] args)
{
Console.Write(format, args);
if (logFileWriter != null)
{
logFileWriter.Write(format, args);
}
}
public static void WriteLine(string format, params object[] args)
{
Console.WriteLine(format, args);
if (logFileWriter != null)
{
logFileWriter.WriteLine(format, args);
}
}
public static void CloseLog()
{
logFileWriter.Flush();
logFileWriter.Close();
}
}
}
Next, open the Program.cs file. You will put the rest of the code for the example in this file.
First, set up the shell of the program. The program will:
- Create a log file so that the request and response can be written to disk for later study.
- Get the email address and password of the account that you'll access.
- Call the sample methods.
Replace the Main method in the Program.cs with the following code.
static void Main(string[] args)
{
// Start tracing to console and a log file.
Tracing.OpenLog("./GetStartedWithEWS.log");
Tracing.WriteLine("EWS sample application started.");
var isValidEmailAddress = false;
Console.Write("Enter an email address: ");
var emailAddress = Console.ReadLine();
isValidEmailAddress = (emailAddress.Contains("@") && emailAddress.Contains("."));
if (!isValidEmailAddress)
{
Tracing.WriteLine("Email address " + emailAddress + " is not a valid SMTP address. Closing program.");
return;
}
SecureString password = GetPasswordFromConsole();
if (password.Length == 0)
{
Tracing.WriteLine("Password empty, closing program.");
}
NetworkCredential userCredentials = new NetworkCredential(emailAddress, password);
// These are the sample methods that demonstrate using EWS.
// ShowNumberOfMessagesInInbox(userCredentials);
// SendTestEmail(userCredentials);
Tracing.WriteLine("EWS sample application ends.");
Tracing.CloseLog();
Console.WriteLine("Press enter to exit: ");
Console.ReadLine();
}
// These method stubs will be filled in later.
private static void ShowNumberOfMessagesInInbox(NetworkCredential userCredentials)
{
}
private static void SendTestEmail(NetworkCredential userCredentials)
{
}
The last thing that you need to do is add the GetPasswordFromConsole static method. This method returns a SecureString object that contains a password typed at the console.
private static SecureString GetPasswordFromConsole()
{
SecureString password = new SecureString();
bool readingPassword = true;
Console.Write("Enter password: ");
while (readingPassword)
{
ConsoleKeyInfo userInput = Console.ReadKey(true);
switch (userInput.Key)
{
case (ConsoleKey.Enter):
readingPassword = false;
break;
case (ConsoleKey.Escape):
password.Clear();
readingPassword = false;
break;
case (ConsoleKey.Backspace):
if (password.Length > 0)
{
password.RemoveAt(password.Length - 1);
Console.SetCursorPosition(Console.CursorLeft - 1, Console.CursorTop);
Console.Write(" ");
Console.SetCursorPosition(Console.CursorLeft - 1, Console.CursorTop);
}
break;
default:
if (userInput.KeyChar != 0)
{
password.AppendChar(userInput.KeyChar);
Console.Write("*");
}
break;
}
}
Console.WriteLine();
password.MakeReadOnly();
return password;
}
Get the number of new messages in an Inbox
A common operation in an EWS application is to get information about email messages, appointments, meetings, and the folders that store them. This example gets the number of messages in an account's Inbox and displays the total number of messages and the number of unread messages. It demonstrates the following common actions for EWS applications:
- Making an EWS request to the Exchange server.
- Parsing the returned XML response for the requested information.
- Handling common exceptions and error messages.
Add the following code to the ShowNumberOfMessagesInInbox method that was stubbed out after the main method. When you run the application, it will print the number of messages in the account's Inbox and the number of unread messages in the Inbox. After you run the application, you can open the GetStartedWithEWS.log file to see the XML request that was sent to the Exchange server and the response that the server returned.
/// This is the XML request that is sent to the Exchange server.
var getFolderSOAPRequest =
"<?xml version=\"1.0\" encoding=\"utf-8\"?>\n" +
"<soap:Envelope xmlns:soap=\"https://schemas.xmlsoap.org/soap/envelope/\"\n" +
" xmlns:t=\"http://schemas.microsoft.com/exchange/services/2006/types\">\n" +
"<soap:Header>\n" +
" <t:RequestServerVersion Version=\"Exchange2007_SP1\" />\n" +
" </soap:Header>\n" +
" <soap:Body>\n" +
" <GetFolder xmlns=\"http://schemas.microsoft.com/exchange/services/2006/messages\"\n" +
" xmlns:t=\"http://schemas.microsoft.com/exchange/services/2006/types\">\n" +
" <FolderShape>\n" +
" <t:BaseShape>Default</t:BaseShape>\n" +
" </FolderShape>\n" +
" <FolderIds>\n" +
" <t:DistinguishedFolderId Id=\"inbox\"/>\n" +
" </FolderIds>\n" +
" </GetFolder>\n" +
" </soap:Body>\n" +
"</soap:Envelope>\n";
// Write the get folder operation request to the console and log file.
Tracing.WriteLine("Get folder operation request:");
Tracing.WriteLine(getFolderSOAPRequest);
var getFolderRequest = WebRequest.CreateHttp(Office365WebServicesURL);
getFolderRequest.AllowAutoRedirect = false;
getFolderRequest.Credentials = userCredentials;
getFolderRequest.Method = "POST";
getFolderRequest.ContentType = "text/xml";
var requestWriter = new StreamWriter(getFolderRequest.GetRequestStream());
requestWriter.Write(getFolderSOAPRequest);
requestWriter.Close();
try
{
var getFolderResponse = (HttpWebResponse)(getFolderRequest.GetResponse());
if (getFolderResponse.StatusCode == HttpStatusCode.OK)
{
var responseStream = getFolderResponse.GetResponseStream();
XElement responseEnvelope = XElement.Load(responseStream);
if (responseEnvelope != null)
{
// Write the response to the console and log file.
Tracing.WriteLine("Response:");
StringBuilder stringBuilder = new StringBuilder();
XmlWriterSettings settings = new XmlWriterSettings();
settings.Indent = true;
XmlWriter writer = XmlWriter.Create(stringBuilder, settings);
responseEnvelope.Save(writer);
writer.Close();
Tracing.WriteLine(stringBuilder.ToString());
// Check the response for error codes. If there is an error, throw an application exception.
IEnumerable<XElement> errorCodes = from errorCode in responseEnvelope.Descendants
("{http://schemas.microsoft.com/exchange/services/2006/messages}ResponseCode")
select errorCode;
foreach (var errorCode in errorCodes)
{
if (errorCode.Value != "NoError")
{
switch (errorCode.Parent.Name.LocalName.ToString())
{
case "Response":
string responseError = "Response-level error getting inbox information:\n" + errorCode.Value;
throw new ApplicationException(responseError);
case "UserResponse":
string userError = "User-level error getting inbox information:\n" + errorCode.Value;
throw new ApplicationException(userError);
}
}
}
// Process the response.
IEnumerable<XElement> folders = from folderElement in
responseEnvelope.Descendants
("{http://schemas.microsoft.com/exchange/services/2006/messages}Folders")
select folderElement;
foreach (var folder in folders)
{
Tracing.Write("Folder name: ");
var folderName = from folderElement in
folder.Descendants
("{http://schemas.microsoft.com/exchange/services/2006/types}DisplayName")
select folderElement.Value;
Tracing.WriteLine(folderName.ElementAt(0));
Tracing.Write("Total messages: ");
var totalCount = from folderElement in
folder.Descendants
("{http://schemas.microsoft.com/exchange/services/2006/types}TotalCount")
select folderElement.Value;
Tracing.WriteLine(totalCount.ElementAt(0));
Tracing.Write("Unread messages: ");
var unreadCount = from folderElement in
folder.Descendants
("{http://schemas.microsoft.com/exchange/services/2006/types}UnreadCount")
select folderElement.Value;
Tracing.WriteLine(unreadCount.ElementAt(0));
}
}
}
}
catch (WebException ex)
{
Tracing.WriteLine("Caught Web exception:");
Tracing.WriteLine(ex.Message);
}
catch (ApplicationException ex)
{
Tracing.WriteLine("Caught application exception:");
Tracing.WriteLine(ex.Message);
}
Send an email message
Another common operation for an EWS application is to send email messages or meeting requests. This example creates and sends an email message using the user credentials that were entered earlier. It demonstrates these common EWS application tasks:
Creating and sending an email.
Parsing the returned XML response to determine if the email was correctly sent.
Handling common exceptions and error messages.
Add the following code to the SendTestEmail method that was stubbed out after the main method. After you run the application, you can open the GetStartedWithEWS.log file to see the XML request that was sent to the Exchange server and the response that the server returned.
var createItemSOAPRequest =
"<?xml version=\"1.0\" encoding=\"utf-8\"?>\n" +
"<soap:Envelope xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" \n" +
" xmlns:m=\"http://schemas.microsoft.com/exchange/services/2006/messages\" \n" +
" xmlns:t=\"http://schemas.microsoft.com/exchange/services/2006/types\" \n" +
" xmlns:soap=\"https://schemas.xmlsoap.org/soap/envelope/\">\n" +
" <soap:Header>\n" +
" <t:RequestServerVersion Version=\"Exchange2007_SP1\" />\n" +
" </soap:Header>\n" +
" <soap:Body>\n" +
" <m:CreateItem MessageDisposition=\"SendAndSaveCopy\">\n" +
" <m:SavedItemFolderId>\n" +
" <t:DistinguishedFolderId Id=\"sentitems\" />\n" +
" </m:SavedItemFolderId>\n" +
" <m:Items>\n" +
" <t:Message>\n" +
" <t:Subject>Company Soccer Team</t:Subject>\n" +
" <t:Body BodyType=\"HTML\">Are you interested in joining?</t:Body>\n" +
" <t:ToRecipients>\n" +
" <t:Mailbox>\n" +
" <t:EmailAddress>sadie@contoso.com</t:EmailAddress>\n" +
" </t:Mailbox>\n" +
" </t:ToRecipients>\n" +
" </t:Message>\n" +
" </m:Items>\n" +
" </m:CreateItem>\n" +
" </soap:Body>\n" +
"</soap:Envelope>\n";
// Write the create item operation request to the console and log file.
Tracing.WriteLine("Get folder operation request:");
Tracing.WriteLine(createItemSOAPRequest);
var getFolderRequest = WebRequest.CreateHttp(Office365WebServicesURL);
getFolderRequest.AllowAutoRedirect = false;
getFolderRequest.Credentials = userCredentials;
getFolderRequest.Method = "POST";
getFolderRequest.ContentType = "text/xml";
var requestWriter = new StreamWriter(getFolderRequest.GetRequestStream());
requestWriter.Write(createItemSOAPRequest);
requestWriter.Close();
try
{
var getFolderResponse = (HttpWebResponse)(getFolderRequest.GetResponse());
if (getFolderResponse.StatusCode == HttpStatusCode.OK)
{
var responseStream = getFolderResponse.GetResponseStream();
XElement responseEnvelope = XElement.Load(responseStream);
if (responseEnvelope != null)
{
// Write the response to the console and log file.
Tracing.WriteLine("Response:");
StringBuilder stringBuilder = new StringBuilder();
XmlWriterSettings settings = new XmlWriterSettings();
settings.Indent = true;
XmlWriter writer = XmlWriter.Create(stringBuilder, settings);
responseEnvelope.Save(writer);
writer.Close();
Tracing.WriteLine(stringBuilder.ToString());
// Check the response for error codes. If there is an error, throw an application exception.
IEnumerable<XElement> errorCodes = from errorCode in responseEnvelope.Descendants
("{http://schemas.microsoft.com/exchange/services/2006/messages}ResponseCode")
select errorCode;
foreach (var errorCode in errorCodes)
{
if (errorCode.Value != "NoError")
{
switch (errorCode.Parent.Name.LocalName.ToString())
{
case "Response":
string responseError = "Response-level error getting inbox information:\n" + errorCode.Value;
throw new ApplicationException(responseError);
case "UserResponse":
string userError = "User-level error getting inbox information:\n" + errorCode.Value;
throw new ApplicationException(userError);
}
}
}
Tracing.WriteLine("Message sent successfully.");
}
}
}
catch (WebException ex)
{
Tracing.WriteLine("Caught Web exception:");
Tracing.WriteLine(ex.Message);
}
catch (ApplicationException ex)
{
Tracing.WriteLine("Caught application exception:");
Tracing.WriteLine(ex.Message);
}
Next steps
Now that you've written your first EWS application, you're ready to discover other ways to use EWS. Here are some ideas to get you started:
Implement Autodiscover in your application so that your application will connect to the correct Exchange server based on the user's email address. See also the Exchange 2013: Get user settings with Autodiscover sample.
Look at the EWS reference for more information about EWS.
See the EWS operations for information about the operations that are available.
Use EWS Editor to see the SOAP traffic sent to and from the server.
If you run into any issues with your application, try posting a question or comment in the forum (and don't forget to read the first post).