Mailbox.makeEwsRequestAsync method (JavaScript API for Office)

apps for Office

Makes an asynchronous request to an Exchange Web Services (EWS) service on the Exchange server that hosts the user’s mailbox.

Last modified: March 04, 2015


App type: Mail

Available in requirement sets


Last changed in Mailbox


Applicable Outlook modes

Compose or read

See all support details

Office.context.mailbox.makeEwsRequestAsync(data, callback, userContext);


The EWS request. Required.


The method to call when the asynchronous load operation is complete. Required.


Any state data that is passed to the asynchronous method. Optional.

The makeEwsRequestAsync method sends an EWS request to Exchange Online, Exchange Online as part of Office 365, or a version of Exchange starting with Exchange 2013 that hosts the user’s mailbox. When the request is complete, the method specified by the callback parameter is called with one parameter, the result object. The result object has two properties: the context property contains the data in the userContext parameter, and the value property contains the XML result of the EWS request. If the result exceeds 1 MB in size, an error message is returned instead.

You cannot request Folder Associated Items with the makeEwsRequestAsync method.

The XML request must specify UTF-8 encoding.

<?xml version="1.0" encoding="utf-8"?>"

Your mail app must have the ReadWriteMailbox permission to use the makeEwsRequestAsync method. For information about using the ReadWriteMailbox permission and the EWS operations that you can call with the makeEwsRequestAsync method, see Specify permissions for mail app access to the user's mailbox.


The server administrator must set "OAuthAuthentication" to true on the Client Access Server EWS directory to enable the makeEwsRequestAsync method to make EWS requests.

Version differences

When you use the makeEwsRequestAsync method in mail apps running in Outlook versions earlier than version 15.0.4535.1004, you should set the encoding value to ISO-8859-1.

<?xml version="1.0" encoding="iso-8859-1"?>"

You do not need to set the encoding value when your mail app is running in Outlook Web App. You can determine whether your mail app is running in Outlook or Outlook Web App by using the mailbox.diagnostics.hostName property. You can determine what version of Outlook is running by using the mailbox.diagnostics.hostVersion property.

In this article, "Outlook" 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. "Outlook rich clients" refers to Outlook for Windows, Outlook for Mac and Outlook RT. 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.

A checkmark (√) in the following table indicates that this property is supported in the corresponding Outlook host application. An empty cell indicates that the Outlook host application doesn't support this property.

For more information about Office host application and server requirements, see Requirements for running apps for Office.

Supported hosts, by platform

Office for Windows desktop

Office for Windows RT

Office Online
(in browser)

OWA for Devices

Office for Mac


√ (Read mode only)

Available in requirement sets


Minimum permission level


App types










© 2015 Microsoft