Create mail add-ins for read forms in Outlook

Office Add-ins

Build mail apps for the read scenario, set up the app manifest and 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: June 02, 2015

Applies to: apps for Office | Office Add-ins | Outlook

Learn more about supported hosts and other requirements.

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.

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

Read apps are mail apps that are activated in the Reading Pane or read inspector in Outlook. Unlike compose apps (mail apps that are activated when a user is creating a message or appointment), read apps are available when users:

  • View an email message, meeting request, meeting response, or meeting cancellation.*

  • View a meeting item in which the user is an attendee.

  • View 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.

* Outlook doesn’t activate mail apps for certain types of messages, 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

For a read app, you must specify the following in the app manifest:

  • The schema version and office.js version. Schema version 1.1 is now required.

  • The appropriate permission level.

  • The appropriate source file to active the app in read forms.

The examples that follow assume that you're using v1.1 of the schema. For information about updating to schema version 1.1, see Update the manifest of a mail add-in from schema v1.0 to v1.1.

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 Create a manifest for a mail add-in 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. Schema version 1.1 is now required.

    <?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 Specify the APIs your mail add-in for Outlook requires.

  2. Specify a version of the office.js in the MinVersion attribute of the Set element.

    <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 add-in 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 add-ins 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:
© 2015 Microsoft