Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Create a mail add-in that runs on desktops, tablets, and mobile devices

Create a mail add-in for Outlook that runs on desktops, tablets, and mobile devices (schema v1.1)

Office Add-ins

Set up your mail add-in in the add-in manifest to work on a desktop, tablet, or smartphone, using the Office Add-ins manifests schema version 1.1.

Last modified: August 10, 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
Customizing source files per form type
Customizing add-in pane dimensions per form type
Tips for designing mail add-ins for desktops, tablets and smartphones
Additional resources

One of the design pillars for Office Add-ins is write-once. For mail add-ins, this means you can create and run an add-in on a desktop, tablet, or smartphone device without necessarily customizing the HTML and JavaScript for each device. The JavaScript API for Office works seamlessly across these devices. You can choose the devices to support, and depending on the user interface design of the mail add-in, decide whether to customize the user interface for each of the selected devices.

A mail app runs on desktop, tablet and smartphone

The MailApp type in the add-in manifest provides the flexibility to customize the UI for specific devices.

<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" 
xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance 
xsi:type="MailApp">

Note that in the previous code, the OfficeApp element specifies using version 1.1 of the Office Add-ins manifests schema. If you have an existing mail add-in that uses schema v1.0, see Update the manifest of a mail add-in from schema v1.0 to v1.1.

Your mail add-ins activate when the user is composing or viewing a message or appointment. If your mail add-in supports both a compose scenario and read scenario, you can use different objects and members in the JavaScript API for Office and provide a different UI for each scenario. To do this, you provide separate source files for the mail add-in for each scenario. Any customization of the mail add-in for devices (desktop, tablet, or smartphone) also depends on whether the add-in is activated in a compose form or read form.

To specify the source files for a mail add-in in the add-in manifest:

  1. Insert the FormSettings and Form elements.

  2. For each type of form (compose or read) that your add-in supports, use the xsi:type attribute to specify ItemEdit or ItemRead as appropriate.

  3. For each type of form, specify the devices that your add-in supports using the corresponding DesktopSettings, TabletSettings, and PhoneSettings elements. You should always include the DesktopSettings element because the desktop computer is the default device. Note that even though you cannot explicitly specify the hosts for your mail add-in, specifying device support lets you determine subsets of hosts that can host your add-in on a tablet or smartphone. For example, specifying support on a tablet means OWA for iPad, Outlook RT, and Outlook Web App can be hosts for your add-in.

  4. For each supported form type and device, specify the location of the corresponding HTML file by using the SourceLocation element. While you should provide distinct source files for compose and read scenarios, within a given scenario, you can choose whether or not to further customize the user interface for each device and provide distinct source files for the supported devices, or simply use the same source file for all the devices.

For example, if you intend your mail add-in to be used on the desktop and tablet devices in a compose scenario, you can use the same source file and specify the DesktopSettings and TabletSettings elements in the add-in manifest as shown below.

<FormSettings>
  <Form xsi:type="ItemEdit">
    <!-- Compose scenario.                    -->
    <!-- Use the same source for each device. -->
    <DesktopSettings>
      <SourceLocation DefaultValue=
        "https://<domain>/source_compose.html" />
    </DesktopSettings>
    <TabletSettings>
      <SourceLocation DefaultValue=
        "https://<domain>/source_compose.html" />
    </TabletSettings>
  </Form>
</FormSettings>

When activated in a compose form, a mail add-in opens in a vertical add-in pane; Outlook adjusts the height and width of the add-in pane dynamically, and you cannot customize either dimension. Table 1 shows the XML elements that you can use in the add-in manifest when specifying source files for various devices in a compose scenario. When activated in a read form, a mail add-in opens in a horizontal add-in pane. For the desktop and tablet devices, you can use the RequestedHeight element to customize the height. You cannot customize the width of the add-in pane. Table 2 shows the XML elements to use to specify source files and any add-in pane customization per device in the read scenario.

Elements for compose scenario

The following table lists the XML elements that you can use to specify source files for each device in a compose scenario. You can specify these elements under the FormSettings element in the add-in manifest.

Table 1. Specifying source files per device in a compose scenario

Device

XML elements in manifest

Supporting hosts

Height of add-in pane

Width of add-in pane

Desktop

Outlook for Windows

Outlook Web App

Cannot specify the desired height.

Cannot specify the desired width.

Tablet

OWA for iPad

Outlook RT

Outlook Web App

Cannot specify the desired height.

Cannot specify the desired width.

Smartphone

OWA for Android

OWA for iPhone

Outlook Web App

Cannot specify the desired height. The add-in pane uses the entire screen of the smartphone.

Cannot specify the desired width.

Elements and add-in pane customization for read scenario

The following lists the XML elements and the kind of customization you can apply to the add-in pane for each device in a read scenario. You can specify these elements under the FormSettings element in the add-in manifest.

Table 2. Specifying source files and add-in pane customization per device in a read scenario

Device

XML elements in manifest

Supporting hosts

Height of add-in pane

Width of add-in pane

Desktop

Outlook for Windows

Specify the desired height using RequestedHeight under DesktopSettings.

Cannot specify the desired width.

Outlook Web App

Specify the desired height using RequestedHeight under DesktopSettings.

Cannot specify the desired width. Outlook Web App uses a 3-column layout.

Tablet

OWA for iPad

Outlook RT

Outlook Web App

Specify the desired height using RequestedHeight under TabletSettings.

Cannot specify the desired width. The host uses a 2-column layout.

Once the add-in pane opens on a tablet, the item body is no longer visible.

Smartphone

OWA for Android

OWA for iPhone

Outlook Web App

Cannot specify the desired height. The add-in pane uses the entire screen of the smartphone.

Cannot specify the desired width. The host uses a single-column layout. Once the add-in pane opens, it occupies the entire screen of the smartphone. The item body is no longer visible.

You do not have control over the width of the add-in pane, and can specify only the desired height of the add-in pane for the desktop and tablet form factors. If you specify a value for RequestedHeight, Outlook for Windows determines the height of the add-in pane to be the lesser of that value and 50% of the height of the Reading Pane or inspector window of that item (whichever is applicable). Outlook for Windows also observes the following limits for the height of an add-in pane:

  • The minimum height for an add-in pane is 32 pixels. If the RequestedHeight element is set to less than 32 pixels, Outlook for Windows displays an add-in pane that is 32 pixels high.

  • The maximum height for an add-in pane is 450 pixels. If the RequestedHeight element is set to more than 450 pixels, Outlook for Windows displays an add-in pane of up to 450 pixels high.

Example

The following example supports both compose and read scenarios, and for each scenario, provides a separate source file for each device. It also customizes the default height of the add-in pane in the read scenario for the desktop and tablet devices.

<FormSettings>
  <Form xsi:type="ItemEdit">
    <!-- Compose scenario allows customizing source -->
    <!-- files, but not add-in pane dimensions.        -->
    <DesktopSettings>
      <SourceLocation DefaultValue=
        "https://<domain>/source_compose_richclient.html" />
    </DesktopSettings>
    <TabletSettings>
      <SourceLocation DefaultValue=
        "https://<domain>/source_compose_tablet.html" />
    </TabletSettings>
    <PhoneSettings>
      <SourceLocation DefaultValue=
        "https://<domain>/source_compose_phone.html" />
    </PhoneSettings>
  </Form>
  <Form xsi:type="ItemRead">
    <!-- Read scenario allows customizing source -->
    <!-- files and height of add-in pane except on  -->
    <!-- the smartphone.                         -->
    <DesktopSettings>
      <SourceLocation DefaultValue=
        "https://<domain>/source_read_richclient.html" />
      <RequestedHeight>350</RequestedHeight>
    </DesktopSettings>
    <TabletSettings>
      <SourceLocation DefaultValue=
        "https://<domain>/source_read_tabet.html" />
      <RequestedHeight>250</RequestedHeight>
    </TabletSettings>
    <PhoneSettings>
      <SourceLocation DefaultValue=
        "https://<domain>/source_read_phone.html" />
    </PhoneSettings>
  </Form>
</FormSettings>

You can generally apply the JavaScript API for Office in a mail add-in the same way regardless of the devices it will run on. You may want to pay attention to the UI design and interaction on different devices though. The following are some tips for displaying an item or opening a pop-up box:

  • You can use the JavaScript window.open method to open pop-up boxes in your mail add-in.

  • Properly encode characters in a URI when specifying the URL argument for window.open.

  • You can use window.open to display an item in the user’s mailbox. To do that:

    • Call the Exchange Web Services GetItem operation to get a URL in the WebClientReadFormQueryString element. The URL is typically of this format:

      https://<somedomain>/owa/#viewmodel=ReadMessageItem&ItemID=<someValidID>&ispopout=1
      
    • Remove the query string &ispopout=1, if it exists.

    • Concatenate the resultant URL with the OWA endpoint and provide it as the input parameter to window.open.

Mail add-ins that activate in read forms on tablets or smartphones

Be aware that when the add-in pane opens on a tablet or smartphone, the item body becomes hidden. To return to the item, the user has to close the add-in.

Mail add-ins that activate in compose forms on tablets or smartphones

Be aware that when the add-in pane opens on a tablet or smartphone, the item body may or may not be visible:

  • If the tablet is in landscape orientation, the item body and add-in pane are adjacent to each other.

  • If the tablet is in portrait orientation, or if the add-in pane is opening on a smartphone, the item body becomes hidden. To return to the item, the user has to close the add-in.

Also, if you're creating a compose add-in that supports tablets or smartphones, note that currently iOS touch devices (iPads, iPhones) do not always automatically provide the user a vertical scroll bar if the content in the add-in pane is longer than the height of the iframe. Follow the guidelines below to enable proper vertical scrolling on such devices:

  • In the CSS for your mail add-in, style the html element with height:100%.

  • Define the body element as follows:

    • height: 100%

    • overflow-y: auto

    • And to support inertial scrolling, -webkit-overflow-scrolling: touch

Show:
© 2015 Microsoft