Create mail add-ins for compose forms in Outlook

Office Add-ins

Build mail add-ins for the compose scenario, set up the add-in manifest, and find API features that are available to compose add-ins.

Last modified: August 07, 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 add-ins for compose forms
API features available to compose add-ins
Additional resources

Starting with version 1.1 of the schema for Office Add-ins manifests and v1.1 of office.js, you can create compose add-ins, which are mail add-ins activated in compose forms in Outlook. In contrast with read add-ins (mail add-ins that are activated in read mode when a user is viewing a message or appointment), compose add-ins 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.

    Note Note

    If the user is on the RTM release of Outlook 2013 and Exchange 2013 and is viewing a meeting item organized by the user, the user can find read add-ins available. Starting in the Office 2013 SP1 release, there’s a change such that in the same scenario, only compose add-ins can activate and 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 Office Add-ins in the ribbon to open the add-in selection pane, and then choose and start a compose add-in. Figure 1 shows the add-in selection pane consisting of 2 compose add-ins, activated when the user is composing an inline reply in Outlook.

Figure 1. The add-in selection pane showing 2 mail add-ins activated for the message that is being composed

Templates mail app activated for composed item

Specifying the manifest for compose add-ins

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

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

    Starting in v1.1, office.js includes API that you can use in compose forms. In order for compose add-ins 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 add-in. This mechanism prevents an add-in showing up in an Outlook host which cannot support the add-in 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 add-in. Further, if the Outlook client of the user does not support that minimum version, the Outlook client would not activate the add-in.

  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 add-in is activated in a compose form, it doesn’t mean the add-in must request permission to write in the form. For example, if your add-in only reads but does not write in a compose form, specify the ReadItem permission. If your add-in sets recipient names of the item in a compose form, specify the ReadWriteItem permission as shown below:


    This permission level tells Exchange Server, Outlook, and customers that your add-in 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 add-in 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 add-in to activate only in compose forms:

      <Rule xsi:type="ItemIs" ItemType="Message" FormType="Edit"/>
    • Specify FormType="ReadOrEdit" if you want the mail add-in 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 add-ins in only read forms. So if you are creating a mail add-in 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 add-in 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 add-in to work in compose forms. As an example, if you specify the following ItemIs rule for the mail add-in 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 add-in for each of compose and read modes:

        <Form xsi:type="ItemRead">
            <SourceLocation DefaultValue="https://webserver/MailAppInReadMode.htm"/>
        <Form xsi:type="ItemEdit">
            <SourceLocation DefaultValue="https://webserver/MailAppInComposeMode.htm"/>

    In each of the source files for read and compose modes, you will design the experience of your add-in 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.

© 2015 Microsoft