Mailbox.makeEwsRequestAsync method (JavaScript API for Office)

Office Add-ins

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

Last modified: August 12, 2015

Note Note

The name "apps for Office" is changing to "Office Add-ins". During the transition, the documentation and the UI of some Office host applications and Visual Studio tools might still use the term "apps for Office". For details, see New name for apps for Office and SharePoint.


Add-in 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 add-in 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 add-in 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 add-ins 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 add-in is running in Outlook Web App. You can determine whether your mail add-in 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.

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 Office Add-ins.

Supported hosts, by platform

Office for Windows desktop

Office Online
(in browser)

OWA for Devices

Office for Mac


√ (Read mode only)

Available in requirement sets


Minimum permission level


Add-in types










© 2015 Microsoft