Create mail apps for compose forms in Outlook

apps for Office

Learn about building mail apps for the compose scenario, how to set up the app manifest and where to find information for available API features. These features include asynchronously adding or removing item attachments, inserting data in the item body, and getting or setting item properties such as subject and recipients.

Last modified: June 05, 2014

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

Note Note

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

   Office.js: v1.1

   Apps for Office manifests schema: v1.1

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

Starting with version 1.1 of the schema for apps for Office manifests and v1.1 of office.js, you can create compose apps, which are mail apps activated in compose forms in Outlook. In contrast with read apps (mail apps that are activated in read mode when a user is viewing a message or appointment), compose apps are available in the following user scenarios:

  • Composing a new message, meeting request, or appointment in a compose inspector.

  • Viewing or editing an existing appointment, or meeting item in which the user is the organizer, in a compose inspector.

    Note Note

    Starting in the Office 2013 SP1 release, in these particular scenarios, only compose apps and not read apps are available. This is different from the same scenarios in the Office 2013 release where read apps would be available.

  • Composing an inline response message or replying to a message in a separate compose inspector.

  • Editing a response (Accept, Tentative, or Decline) to a meeting request or meeting item.

  • Proposing a new time for a meeting item.

  • Forwarding or replying to a meeting request or meeting item.

In each of these compose scenarios, users can choose Apps for Office in the ribbon to open the app selection pane, and then choose and start a compose app. Figure 1 shows the app selection pane consisting of 2 compose apps, activated when the user is composing an inline reply in Outlook.

Figure 1. The app selection pane showing 2 mail apps activated for the message that is being composed

Templates mail app activated for composed item

Specifying the manifest for compose apps

There are a few things you must specify in the app manifest for a compose app – the appropriate versions of the schema and office.js, the appropriate permission level, and getting the app activated in compose forms with the appropriate source file. 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 to be at least v1.1. The following XML 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">
    
  2. Use the MinVersion attribute of the Set element to specify that your mail app requires Exchange Server and the host to support at least office.js v1.1. The following is an XML example:

    <Requirements>
      <Sets DefaultMinVersion="1.1">
        <Set MinVersion="1.1" Name="Mailbox"></Set>
      </Sets>
    </Requirements>
    

    Starting in v1.1, office.js includes API that you can use in compose forms. In order for compose apps to install and run, Exchange and Outlook have to support such API as well.

    minVersion is not limited to supporting compose-related API. In general, make sure that the minimum version you specify as minVersion includes all the objects and members that you need in your mail app. This mechanism prevents an app showing up in an Outlook host which cannot support the app properly: If the Exchange Server of the user's mailbox does not support that minimum version of office.js, the user or administrator would not be able to install the app. Further, if the Outlook client of the user does not support that minimum version, the Outlook client would not activate the app.

  3. Use the Permissions element to specify the minimum necessary permission, depending on the exact read or compose methods that you plan to use. Remember, even though an app is activated in a compose form, it doesn’t mean the app must request permission to write in the form. For example, if your app only reads but does not write in a compose form, specify the ReadItem permission. If your app sets recipient names of the item in a compose form, specify the ReadWriteItem permission as shown below:

    <Permissions>ReadWriteItem</Permissions>
    

    This permission level tells Exchange Server, Outlook, and customers that your app requires the permission to read and write to the message or appointment being authored. This access includes getting and setting recipient names, email addresses, subject, body and attachments of that item.

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

  4. Use an ItemIs rule and specify the FormType attribute in one of the following ways:

    • Specify FormType="Edit" if you want the mail app to activate only in compose forms:

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

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

    There are other types of activation rules - ItemHasAttachment, ItemHasKnownEntity, and ItemHasRegularExpressionMatch – that the schema supports, but these rules activate mail apps in only read forms. So if you are creating a mail app to be activated in a compose or read form, make sure you don't combine this ItemIs rule with the other rule types with an "AND" operation, or your mail app will not be activated in compose forms.

  5. Use the FormSettings, Form and SourceLocation elements to specify the appropriate source HTML file for the mail app to work in compose forms. As an example, if you specify the following ItemIs rule for the mail app to activate in compose or read mode:

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

    Then you should specify separate source files for your mail app for each of compose and read modes:

    <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 the experience of your app in respectively a read form and 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