Customize Outlook Web App

Exchange Server 2013

Customize your Outlook Web App for Exchange Online, Exchange Online as part of Office 365, or versions of Exchange starting with Exchange 2013.

Last modified: March 05, 2014

Applies to: apps for Office | Exchange Server 2013 | Office 365 | Outlook 2013 | Outlook Web App | OWA for Devices

Starting with Exchange Server 2013, you can customize your Outlook Web App in two ways:

  • By customizing Outlook Web App themes to change how the application looks.

  • By using mail apps to create a custom experience for your users.

You can find instructions for customizing pages and creating a theme for Outlook Web App on TechNet in the following articles:

Mail apps provide a single interface and programming model that use web standards to create a custom app for your users. Your mail app can be simple or complex, run when a user is reading an email or when composing an email, use data from an Exchange server or from any service on the web, and fully integrate with both Outlook Web App and Outlook 2013.

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

Mail apps use the following standard web technologies in a collapsible frame on the client screen to enable your users to interact with the app:

  • XML – The manifest file that describes your mail app is an XML document. The manifest provides a description of your mail app, tells Outlook Web App where your mail app can be found, and tells Outlook Web App the conditions in which to render your mail app. For more information about the manifest file, see Schema reference for apps for Office manifests (v1.1).

  • HTML 5 – The user interface for your mail app is written in HTML 5, the emerging standard for web pages. For information about how to use HTML 5 to create a UI for your mail app, see Apps for Office UX design guidelines.

  • JavaScript – Outlook Web App provides a JavaScript API that you use to create the business logic for your application. For information about how to use JavaScript in a mail app, see JavaScript API for Office (v1.1).

At least three servers are involved in delivering your mail app to Outlook Web App. The first is the Exchange server, which provides the user's mailbox and the manifest files for mail apps that the user has installed. The second is a web server that you maintain that provides the scripts and HTML that make up your mail app. The third is a server provided by Microsoft that provides the JavaScript library files.

Figure 1. The flow of events involved in starting a mail app in the Outlook Web App or Outlook 2013

Flow of events when starting Outlook mail app

A mail app can transfer information attached to an email or appointment message from an Exchange server to the server that hosts the mail app. For example, a mail app that archives attached photographs can provide a UI that enables the user to transfer photos attached to the message.

You can also transfer an entire email message from the Exchange server to the host server. An off-site email repository, for example, could use this method to archive email message.

In both cases, the mail app gets a callback token from the Exchange server that it pass along to your service application. Your service application uses the callback token in an Exchange Web Services (EWS) request to retrieve the attachment or email item.

You can connect your mail app for Outlook Web App to any web service to provide information to your clients.

Connecting to EWS

The JavaScript API for mail apps includes the makeEwsRequestAsync function that you can use to call a subset of Exchange Web Services (EWS) on the Exchange server that hosts the user's email account. For example, you can use the getEntities function to find out whether an email message includes phone numbers, and then call EWS to look up the numbers in the address book so that you can show the contact information that is associated with phone numbers that are stored in Exchange.

For more information about using EWS in a mail app, see Call web services from a mail app for Outlook.

Connecting to web services on your mail app web server

You can access web services that run on the same web server that hosts the HTML UI for your mail app. The JavaScript API for mail apps includes the getUserIdentitytoken function that returns a JSON Web Token that your web service can use to associate an email account on the Exchange server with an account on your service. You can use this token as part of signing in to your service, or you can use this token as part of a single sign-on solution for your mail app clients.

If you are using the .NET Framework for your service, the EWS Managed API includes a validation library that you can use on the server to validate the user identity token sent from the Exchange server. If you are using another programming language, such as Ruby or PHP, you can validate the token using those languages as well.

For more information about using the user identity token, see Authenticate a mail app by using Exchange identity tokens.

Web services from the Internet

Your mail app can also provide information from any web service on the Internet by using a proxy that runs on your mail app web server. You can't get data directly from another web service, the web browser will return a cross-site scripting error; however, your proxy web server can access and provide the information. You can use the user identity token to identify authorized users or to provide a single sign-on solution.

You can design the UI of your mail app however you like. Your mail app integrates into the reading experience for your user; it will run in a pane that is as wide as the reading area and is between 32 and 350 pixels tall. Within that area you can create the user experience that will make your mail app stand out.

Figure 1. Bing Map mail app activated for a message in Outlook

Bing Map mail app in Outlook

The following are some suggested design guidelines for your mail app:

  • Use Microsoft design style – The new interface for Outlook Web App and Outlook is inspired by the Microsoft design style initiative.

  • Dimensions – Use the smallest dimensions that you can for your mail app. The mail app should blend in with the message reading experience.

  • Borders and margins – The Outlook Web App UI will display a border around your mail app. If appropriate, fill the UI with your app by setting the margins to zero.

  • Scrolling – Your mail app is displayed in a scrolling window. Adding another scroll bar can be confusing for readers. Use paging for long displays of information.

  • Navigation – When you use paging for your mail app, remember to include navigation both forward and backward through the content. You can use complex structures, such as pivots and tabs, to present structured information to your reader.

  • Design for the device – Mail apps can be shown on the desktop, on a tablet, or on a smart phone. You can usually use the same UI for a tablet and a desktop system, but you should provide a separate UI designed specifically for the reduced screen size of a smart phone for the best experience.

Note Note

For a more detailed discussion of design guidelines for mail apps, see Apps for Office and SharePoint UX guidelines.

Mail apps for Outlook Web App and Outlook use standard web technologies; you can use the same tools that you use to create web sites to create a mail app. Visual Studio 2012 with the Apps for Office Tools provides an IDE for creating, deploying, and testing mail apps; however, you can use a text editor to create a mail app as well. To create your first mail app, see one of these two articles:

© 2014 Microsoft