Use Exchange Web Services (EWS) from an Outlook add-in

Your Outlook add-in can use Exchange Web Services (EWS) from an environment that runs Exchange Server (on-premises). EWS is a web service that's available on the server that provides the source location for the add-in's UI. This article provides an example that shows how an Outlook add-in can request information from EWS.

The way you call a web service varies based on where the web service is located. The following tables list the different ways you can call a web service based on location.

Using the makeEwsRequestAsync method to access EWS operations

You can use the mailbox.makeEwsRequestAsync method to make an EWS request to the on-premises Exchange server that hosts the user's mailbox.

EWS supports different operations on an Exchange server; for example, item-level operations to copy, find, update, or send an item, and folder-level operations to create, get, or update a folder. To perform an EWS operation, create an XML SOAP request for that operation. When the operation finishes, you get an XML SOAP response that contains data that's relevant to the operation. EWS SOAP requests and responses follow the schema defined in the Messages.xsd file. Like other EWS schema files, the Message.xsd file is located in the IIS virtual directory that hosts EWS.

To use the makeEwsRequestAsync method to initiate an EWS operation, provide the following:

• The XML for the SOAP request for that EWS operation as an argument to the data parameter.

• A callback function (as the callback argument).

• Any optional input data for that callback function (as the userContext argument).

When the EWS SOAP request is complete, Outlook calls the callback function with one argument, which is an AsyncResult object. The callback function can access two properties of the AsyncResult object: the value property, which contains the XML SOAP response of the EWS operation, and optionally, the asyncContext property, which contains any data passed as the userContext parameter. Typically, the callback function then parses the XML in the SOAP response to get any relevant information and processes that information accordingly.

Tips for parsing EWS responses

When parsing a SOAP response from an EWS operation, note the following browser-dependent issues.

• Specify the prefix for a tag name when using the DOM method getElementsByTagName to include support for Internet Explorer and the Trident webview.

  getElementsByTagName behaves differently depending on browser type. For example, an EWS response can contain the following XML (formatted and abbreviated for display purposes).

  <t:ExtendedProperty><t:ExtendedFieldURI PropertySetId="00000000-0000-0000-0000-000000000000" 
  PropertyName="MyProperty" 
  PropertyType="String"/>
  <t:Value>{
  ...
  }</t:Value></t:ExtendedProperty>
  

  Code, as in the following, would work on a browser like Chrome to get the XML enclosed by the ExtendedProperty tags.

  const mailbox = Office.context.mailbox;
  mailbox.makeEwsRequestAsync(mailbox.item.itemId, (result) => {
       const response = $.parseXML(result.value);
       const extendedProps = response.getElementsByTagName("ExtendedProperty")
  });
  

  For the Trident (Internet Explorer) webview, you must include the t: prefix of the tag name, as follows.

  const mailbox = Office.context.mailbox;
  mailbox.makeEwsRequestAsync(mailbox.item.itemId, (result) => {
       const response = $.parseXML(result.value);
       const extendedProps = response.getElementsByTagName("t:ExtendedProperty")
  });
  

• Use the DOM property textContent to get the contents of a tag in an EWS response, as follows.

  content = $.parseJSON(value.textContent);
  

  Other properties such as innerHTML may not work on the Trident (Internet Explorer) webview for some tags in an EWS response.

Example

The following example calls makeEwsRequestAsync to use the GetItem operation to get the subject of an item. This example includes the following three functions.

• getSubjectRequest – Takes an item ID as input, and returns the XML for the SOAP request to call GetItem for the specified item.

• sendRequest – Calls getSubjectRequest to get the SOAP request for the selected item, then passes the SOAP request and the callback function, callback, to makeEwsRequestAsync to get the subject of the specified item.

• callback – Processes the SOAP response, which includes any subject and other information about the specified item.

function getSubjectRequest(id) {
   // Return a GetItem operation request for the subject of the specified item. 
   const result = 
    '<?xml version="1.0" encoding="utf-8"?>' +
    '<soap:Envelope xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"' +
    '               xmlns:xsd="https://www.w3.org/2001/XMLSchema"' +
    '               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"' +
    '               xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">' +
    '  <soap:Header>' +
    '    <RequestServerVersion Version="Exchange2013" xmlns="http://schemas.microsoft.com/exchange/services/2006/types" soap:mustUnderstand="0" />' +
    '  </soap:Header>' +
    '  <soap:Body>' +
    '    <GetItem xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">' +
    '      <ItemShape>' +
    '        <t:BaseShape>IdOnly</t:BaseShape>' +
    '        <t:AdditionalProperties>' +
    '            <t:FieldURI FieldURI="item:Subject"/>' +
    '        </t:AdditionalProperties>' +
    '      </ItemShape>' +
    '      <ItemIds><t:ItemId Id="' + id + '"/></ItemIds>' +
    '    </GetItem>' +
    '  </soap:Body>' +
    '</soap:Envelope>';

   return result;
}

function sendRequest() {
   // Create a local variable that contains the mailbox.
   const mailbox = Office.context.mailbox;

   mailbox.makeEwsRequestAsync(getSubjectRequest(mailbox.item.itemId), callback);
}

function callback(asyncResult)  {
   const result = asyncResult.value;
   const context = asyncResult.context;

   // Process the returned response here.
}

EWS operations that add-ins support

Outlook add-ins can access a subset of operations that are available in EWS via the makeEwsRequestAsync method. If you're unfamiliar with EWS operations and how to use the makeEwsRequestAsync method to access an operation, start with a SOAP request example to customize your data argument.

The following describes how you can use the makeEwsRequestAsync method.

1. In the XML, substitute any item IDs and relevant EWS operation attributes with appropriate values.

2. Include the SOAP request as an argument for the data parameter of makeEwsRequestAsync.

3. Specify a callback function and call makeEwsRequestAsync.

4. In the callback function, verify the results of the operation in the SOAP response.

5. Use the results of the EWS operation according to your needs.

The following table lists the EWS operations that add-ins support. To see examples of SOAP requests and responses, choose the link for each operation. For more information about EWS operations, see EWS operations in Exchange.

Authentication and permission considerations for makeEwsRequestAsync

When you use the makeEwsRequestAsync method, the request is authenticated by using the email account credentials of the current user. The makeEwsRequestAsync method manages the credentials for you so that you don't have to provide authentication credentials with your request.

To use the makeEwsRequestAsync method, your add-in must request the read/write mailbox permission in the manifest. The markup varies depending on the type of manifest.

• Add-in only manifest: Set the <Permissions> element to ReadWriteMailbox.
• Unified manifest for Microsoft 365: Set the "name" property of an object in the "authorization.permissions.resourceSpecific" array to "Mailbox.ReadWrite.User".

For information about using the read/write mailbox permission, see read/write mailbox permission.

See also

• Privacy and security for Office Add-ins
• Addressing same-origin policy limitations in Office Add-ins
• EWS reference for Exchange
• Mail apps for Outlook and EWS in Exchange

See the following for creating backend services for add-ins using ASP.NET Web API.

• Create a web service for an Office Add-in using the ASP.NET Web API
• The basics of building an HTTP service using ASP.NET Web API