Edit

Outlook add-ins and EWS in Exchange

  • Article

Find information about Outlook add-ins and how they work with EWS in Exchange.

Outlook add-ins provide a single interface and programming model that uses web standards to enable you to create a custom experience for your email users. You can create mail apps that display contextual or helpful information in an HTML5 frame hosted in Outlook; for example, a mail app can show a Bing map with an address highlighted when an email message contains an address. Or when a user is composing a message, a mail app can show additional information about the recipient, and insert a standard greeting into the email at the touch of a button.

Note

"Outlook" in this article refers to the Outlook rich client, Outlook RT, Outlook Web App, and OWA for Devices.

The mail apps interface is part of the JavaScript API for Office. You can use the API to access information in Exchange to enable your mail app to:

  • Recognize entities, like addresses, phone numbers, task suggestions, or meeting suggestions in an email.

  • Open and display existing messages and appointments in a separate view so that users can cross-reference information in one or more messages.

  • Make EWS requests to the Exchange server that hosts the user's mailbox. A mail app can, for example, get a list of folders so that the user can choose one to store the message, or show all the items in a conversation, or mark an email message as junk.

  • Get a token to uniquely identify an email account to enable single sign on on a third-party service.

  • Get a token that enables a third-party service to make EWS requests on behalf of the user, for example, to extract the attachments from an item, or to get an item from the Exchange server for further processing.

You can use mail apps to customize the Outlook Web App experience for your users; if, however, you want to customize the "look and feel" of Outlook Web App, see these articles on TechNet:

Your organization can install mail apps on an internal server to limit access to authorized users, or you and other mail app developers can put mail apps on the Office Store for sale to the general public. Anyone who is running Outlook can download, install, and use mail apps from the marketplace.

If you want to learn more about creating mail apps, check out the Outlook add-ins documentation or the Make an EWS request sample.

EWS and Outlook add-ins

You can use a subset of EWS operations on the Exchange server that hosts the account that runs a mail app.

The mailbox.makeEwsRequestAsync function enables you to make EWS requests from your mail app back to the server that hosts the user's mailbox. You create the SOAP envelope and XML request, and the makeEwsRequestAsync function calls EWS with an authentication token that identifies the mailbox and mail app that is making the request. To help secure the user's mailbox, the Exchange server will reject any requests that do not come from the mail app or from a mailbox that is not hosted on the server.

Like any other application, a mail app needs permissions to work. Your administrator needs to:

You also need to make sure that your app requests the read/write mailbox permission in the apps for Office permission model.

When these steps are complete, a subset of folder and item EWS operations are available for the mail app to use.

Table 1. EWS folder and item operations that mail apps can use

Folder operations Item operations
CreateFolder operation
FindFolder operation
GetFolder operation
UpdateFolder operation
CopyItem operation
CreateItem operation
FindItem operation
FindConversation operation
GetConversationItems operation
GetItem operation
MarkAsJunk operation
MoveItem operation
SendItem operation
UpdateItem operation

Service callback tokens

Service callback tokens enable mail apps to pass an access token to a third-party service so that the service can make EWS requests to the Exchange server that hosts the mailbox. For example, a mail app can pass a service callback token to a third-party service along with a list of attachment IDs for pictures attached to an email. The service can then use the attachment IDs and the callback token to make an EWS request to the user's Exchange server to get the attached pictures. Mail apps can also use the service callback token with a list of item IDs to get email and appointment items from the Exchange server.

The service callback token is an opaque token that the third-party service attaches to the EWS request in a bearer authentication header. The token identifies the mail app and the mailbox to help secure the EWS request. To learn how to use service callback tokens, see the Outlook add-ins: Get attachments from an Exchange server sample.

See also