Create mail apps for read forms in Outlook
Learn about building mail apps for the read scenario, how to set up the app manifest and where to find information for available API features. These features include contextual activation based on message class, the existence of an attachment, or string matching by regular expressions or well-known entities, and getting attachments of an item.
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 for Mac for Office 365 | Outlook Web App | OWA for Devices
Office.js: v1.0, v1.1
Apps for Office manifests schema: v1.1
Using any version of the schema for the apps for Office manifests and office.js, you can create read apps, which are mail apps activated in the Reading Pane or read inspector in Outlook. In contrast with compose apps (mail apps that are activated when a user is creating a message or appointment), read apps are available in the following user scenarios:
Viewing an email message, meeting request, meeting response, or meeting cancellation.*
Viewing a meeting item in which the user is an attendee.
Viewing a meeting item in which the user is the organizer (RTM release of Outlook 2013 and Exchange 2013 only)
Starting in the Office 2013 SP1 release, if the user is viewing a meeting item that the user has organized, only compose apps can activate and be available. Read apps are no longer available in this scenario.
* There are types of messages for which Outlook doesn’t activate mail apps, including items that are attachments to another message, and items in the Outlook Drafts or Junk Email folder, or encrypted or protected in other ways.
In each of these read scenarios, Outlook activates mail apps when their activation conditions are fulfilled, and users can choose and open activated mail apps in the app bar in the Reading Pane or read inspector. Figure 1 shows a Bing Maps mail app activated and opened as the user is reading a message that contains a geographic address.
Specifying the manifest for read apps
The examples below assume using at least v1.1 of the schema. For information about creating a manifest for a read app using schema v1.0, see Creating a manifest for a mail app to activate in a read form in Outlook (schema v1.0).
Note that there are other XML elements you should specify for mail apps based on the schema, and these elements should occur in a specific order in the manifest. Refer to the Definition section of MailApp complexType for the order, and Creating a manifest for a mail app to activate in a read or compose form in Outlook (schema v1.1).
Specify a version of the schema at the beginning of the app manifest. All versions of the schema support read apps. You should choose the versions of the schema and of office.js based on the features you need for your app. The following XML example specifies using v1.1 of the schema:
<?xml version="1.0" encoding="utf-8"?> <OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="MailApp">
For more information about choosing a version based on the available features, see Choosing a version of the platform for your mail app for Outlook.
Specify a version of the office.js in the MinVersion attribute of the Set element. All versions of office.js support read apps. Choose a version of office.js that works with the version of the schema you specified in the last step, and that supports the mandatory features for your app. For example, if you chose schema v1.1 in the last step, then you should specify at least v1.1 of office.js, as in the following XML example:
Specify an appropriate level of permissions for your app in the Permissions element. The supported levels of permission depend on the version of schema you have chosen. In general, choose the minimum necessary permission that offers access to the set of API that your app uses, taking into consideration all mandatory and optional features. The following example uses schema v1.1 and shows a mail app requesting ReadItem permission:
For more information about permission levels and the functionality each level supports, see Specify permissions for mail app access to the user's mailbox.
Use one or more of the activation rules that are supported in read mode. For example, for schema v1.1, the rules for read mode are ItemHasAttachment, ItemHasKnownEntity, and ItemHasRegularExpressionMatch, and ItemIs. For an ItemIs rule, specify the FormType attribute in one of the following ways:
Specify FormType="Edit" if you want the mail app to activate only in read forms:
Specify FormType="ReadOrEdit" if you want the mail app to activate in compose and read forms:
Note that for activating mail apps in read forms, the ItemIs rule is optional, and if the rule is not specified, Outlook would activate the mail app based on other existing rules in the manifest. For more information about activation rules, see Activate mail apps in Outlook clients.
Use the FormSettings, Form and SourceLocation elements to specify the appropriate source HTML file for the mail app to work in read forms. As an example, if you specify the following ItemIs rule for the mail app to activate in read mode:
Then you should specify a source file for your mail app under the form type ItemRead:
<FormSettings> <Form xsi:type="ItemRead"> <DesktopSettings> <SourceLocation DefaultValue="https://webserver/MailAppInReadMode.htm"/> <RequestedHeight>250</RequestedHeight> </DesktopSettings> </Form> </FormSettings>
As another example, if you specify the following ItemIs rule for a mail app that works in both read and compose forms:
Then you should specify separate source files for your app, one for read mode under the form type ItemRead, and another for compose mode under the form type ItemEdit:
<FormSettings> <Form xsi:type="ItemRead"> <DesktopSettings> <SourceLocation DefaultValue="https://webserver/MailAppInReadMode.htm"/> <RequestedHeight>250</RequestedHeight> </DesktopSettings> </Form> <Form xsi:type="ItemEdit"> <DesktopSettings> <SourceLocation DefaultValue="https://webserver/MailAppInComposeMode.htm"/> </DesktopSettings> </Form> </FormSettings>
For activating apps in read forms: see Table 1 in Specifying activation rules in a manifest.