Create mail apps for read forms in Outlook

apps for Office

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: August 14, 2014

Applies to: Exchange Online | Exchange Server 2013 | Exchange Server 2013 SP1 | Outlook 2013 | Outlook 2013 RT | Outlook 2013 SP1 | Outlook Web App | OWA for Devices

   Office.js: v1.0, v1.1

   Apps for Office manifests schema: v1.1

Note Note

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

In this article
Setting up mail apps for read forms
API features available to read apps
In this section
Additional resources

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)

    Note Note

    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.

Figure 1. The app pane showing the Bing Maps mail app in action for the selected Outlook message that contains an address

Bing Map mail app in Outlook

Specifying the manifest for read apps

There are a few things you must specify in the app manifest for a read app – the appropriate versions of the schema and office.js, the appropriate permission level, and getting the app activated in read forms with the appropriate source file. The ways to do several of these things depend on the version of the schema you have chosen. In particular, if you are creating a new app and trying to decide between v1.0 and v1.1 or a later version, because of the extensive changes that v1.1 has brought forward, you should use at least v1.1. Because schema v1.1 is compatible with office.js v1.1, if you update the manifest to use v1.1, even if you do not update the JavaScript calls in your app, you should update the HTML file of your app to include office.js v1.1.

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).

  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.

  2. 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:

    <Requirements>
      <Sets DefaultMinVersion="1.1">
        <Set MinVersion="1.1" Name="Mailbox"></Set>
      </Sets>
    </Requirements>
    
  3. 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:

    <Permissions>ReadItem</Permissions>
    

    For more information about permission levels and the functionality each level supports, see Specify permissions for mail app access to the user's mailbox.

  4. 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:

      <Rule xsi:type="ItemIs" ItemType="Message" FormType="Read"/>
      
    • Specify FormType="ReadOrEdit" if you want the mail app to activate in compose and read forms:

      <Rule xsi:type="ItemIs" ItemType="Message" FormType="ReadOrEdit"/>
      

    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.

  5. 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:

    <Rule xsi:type="ItemIs" ItemType="Message" FormType="Read"/>
    

    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:

    <Rule xsi:type="ItemIs" ItemType="Message" FormType="ReadOrEdit"/>
    

    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>
    

    In each of the source files for read and compose modes, you will design one experience for your app in a read form, and another experience in a compose form. There are features and corresponding objects and members in the JavaScript API for Office that work in only read forms, and ones only in compose forms, and hence it's a better practice to separate the source files for each Outlook mode.

Show:
© 2014 Microsoft