Export (0) Print
Expand All

Call web services from a mail app for Outlook

apps for Office

Learn about how to call EWS or other web services from a mail app for Outlook.

Last modified: November 14, 2014

Applies to: Exchange Online | Exchange Server 2013 | Exchange Server 2013 SP1 | Outlook 2013 | Outlook 2013 RT | Outlook 2013 SP1 | Outlook Web App | OWA for Devices

   Office.js: v1.0, v1.1

   Apps for Office manifests schema: v1.0, v1.1

Note Note

"Outlook" in this article refers to Outlook for Windows, Outlook for Mac, Outlook RT, OWA for Devices (OWA for Android phones, OWA for iPad, OWA for iPhone), and Outlook Web App. At this point, Outlook for Mac supports JavaScript API for Office in only Outlook read mode, and can activate mail apps that reference office.js version 1.0 or 1.1 and use apps for Office schema version 1.0.

Your mail app can use Exchange Web Services (EWS) from a computer that is running Exchange Server 2013, a web service that is available on the server that provides the source location for the mail app's UI, or a web service that is available on the Internet. This article provides an example that shows how a mail app can request information from EWS.

The way that you call a web service varies based on where the web service is located. Table 1 lists the different ways that you can call a web service based on location.

Table 1. Ways to call web services from a mail app

Web service location

Way to call the web service

The Exchange server that hosts the client mailbox

Use the makeEwsRequestAsync method to call EWS operations that mail apps support. You can access this method from the Mailbox object, which represents the user's mailbox. The Exchange server that hosts the mailbox also exposes EWS.

The web server that provides the source location for the app UI

Call the web service by using standard JavaScript techniques. The JavaScript code in the UI frame runs in the context of the web server that provides the UI. Therefore, it can call web services on that server without causing a cross-site scripting error.

All other locations

Create a proxy for the web service on the web server that provides the source location for the UI. If you do not provide a proxy, cross-site scripting errors will prevent your mail app from running. One way to provide a proxy is by using JSON/P. For more information, see Privacy and security for apps for Office.

You can use the Mailbox.makeEwsRequestAsync method to make a EWS request to the 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 a EWS operation, create an XML SOAP request for that operation. When the operation finishes, you get an XML SOAP response that contains data that is 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 a EWS operation, provide the following:

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

  • A callback method (as the callback argument)

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

When the EWS SOAP request is complete, Outlook calls the callback method with one argument, which is an AsyncResult object. The callback method 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 method then parses the XML in the SOAP response to get any relevant information, and processes that information accordingly.

When parsing a SOAP response from a 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.

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

    <t:ExtendedProperty><t:ExtendedFieldURI PropertySetId="00000000-0000-0000-0000-000000000000" 

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

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

    On Internet Explorer, you must include the t: prefix of the tag name, as shown below:

    var mailbox = Office.context.mailbox;
    mailbox.makeEwsRequestAsync(mailbox.item.itemId), function(result) {
        var response = $.parseXML(result.value);
        var extendedProps = response.getElementsByTagName("t:ExtendedProperty");
  • Use the DOM property textContent to get the contents of a tag in a EWS response, as shown below:

    content = $.parseJSON(value.textContent);

    Other properties such as innerHTML may not work on Internet Explorer for some tags in a EWS response.

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 method, 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. 
   var result = 
'<?xml version="1.0" encoding="utf-8"?>' +
'<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"' +
'               xmlns:xsd="http://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>' +

   return result;

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

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

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

   // Process the returned response here.

Mail apps can access a subset of operations that are available in EWS via the makeEwsRequestAsync method. If you are 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 method and call makeEwsRequestAsync.

  4. In the callback method, 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 mail apps 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 2013.

Table 2. Supported EWS operations

EWS operation


CopyItem operation

Copies the specified items and puts the new items in a designated folder in the Exchange store.

CreateFolder operation

Creates folders in the specified location in the Exchange store.

CreateItem operation

Creates the specified items in the Exchange store.

FindConversation operation

Enumerates a list of conversations in the specified folder in the Exchange store.

FindFolder operation

Finds subfolders of an identified folder and returns a set of properties that describe the set of subfolders.

FindItem operation

Identifies items that are located in a specified folder in the Exchange store.

GetConversationItems operation

Gets one or more sets of items that are organized in nodes in a conversation.

GetFolder operation

Gets the specified properties and contents of folders from the Exchange store.

GetItem operation

Gets the specified properties and contents of items from the Exchange store.

MarkAsJunk operation

Moves email messages to the Junk Email folder, and adds or removes senders of the messages from the blocked senders list accordingly.

MoveItem operation

Moves items to a single destination folder in the Exchange store.

SendItem operation

Sends email messages that are located in the Exchange store.

UpdateFolder operation

Modifies the properties of existing folders in the Exchange store.

UpdateItem operation

Modifies the properties of existing items in the Exchange store.

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 do not have to provide authentication credentials with your request.

Note Note

The server administrator must use the New-WebServicesVirtualDirctory or the Set-WebServicesVirtualDirecory cmldet to set the OAuthAuthentication parameter to true on the Client Access server EWS directory in order to enable the makeEwsRequestAsync method to make EWS requests.

Your mail app must specify the ReadWriteMailbox permission in its app manifest to use the makeEwsRequestAsync method. For information about using the ReadWriteMailbox permission, see the section Read/write mailbox permission in Specify permissions for mail app access to the user's mailbox, and Creating a manifest for a mail app to activate in a read or compose form in Outlook (schema v1.1).

© 2014 Microsoft