Specify the APIs your mail add-in for Outlook requires

Office Add-ins

Specify the version of the Office Add-ins platform that includes the features and functionality that you need for your mail add-in.

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
What specifying the version of the Office Add-ins platform means for mail add-in
Define the version of the Office Add-ins platform
Additional resources

When you develop Office Add-ins, you choose the level of API support your add-in needs by specifying the minimum version of the of the Mailbox requirement set in the add-in manifest. This helps ensure that your add-in runs in an Outlook host that supports the specified APIs.

For mail add-in, you specify:

  • The version of the add-in manifest schema.

    Note Note

    Manifest schema version 1.1 is required.

  • The minimum required version of the Mailbox requirements set.

How to specify the manifest schema

Your add-in must use manifest schema version 1.1. If have an add-in that uses version 1.0, see Update the manifest of a mail add-in from schema v1.0 to v1.1.

How to specify the Mailbox requirement set

The minimum required version of the Mailbox requirement set is the earliest version that supports the APIs used to implement required features of your add-in. The desired version of office.js is the version that supports the APIs used to implement all the optional features of your add-in. This might be the same as the minimum required version.

When the desired version is different from the minimum required version, your add-in might be installed and activated on a host that doesn't support all the elements your add-in needs. Determine whether the user's Exchange and Outlook versions support the APIs your add-in requires. If those APIs aren’t supported, you'll need conditional code that keeps your add-in working. For information about how to write conditional code, see Use if statements to determine whether a host application supports an API member.

For mail add-in, you must specify the "Mailbox" requirement set in the manifest. Specify the minimum required version of the APIs your add-in uses in this requirement set in the MinVersion attribute of the Set element. For example, if your add-in uses the Appointment.addFileAttachmentAsync method, you must specify the MinVersion attribute as at least 1.1, because that's the version of the Mailbox API when this method was introduced. You can find this information in the https://msdn.microsoft.com/en-us/library/office/dn482463#bk_history section of an API reference topic.

The Methods element doesn’t apply to mail add-in, so you can’t declare support for specific methods.

To define the version of the Office Add-ins platform that your mail add-in requires:

  1. Decide on a scenario for your mail add-in and identify the features that the mail add-in will use for that scenario. Determine which features are required and which are optional.

  2. In the <head> tag of the web page ( .html, .aspx, or .php file) that implements the UI of your add-in, add a script tag with its src attribute set to the content delivery network (CDN) URL of JavaScript API for Office library:

    <script src="https://appsforoffice.microsoft.com/lib/1/hosted/Office.js" type="text/javascript"></script>
    

    The /1/ in front of office.js in the CDN URL specifies to use the latest incremental release within version 1 of Office.js. Because the JavaScript API for Office maintains backward compatibility, the latest release will continue to support API members that were introduced earlier in version 1.

  3. Specify the Requirements, Sets, and Set elements to require the Mailbox API:

    • Set the Name attribute of the Set element as "Mailbox". You have to specify this value for Exchange to install the mail add-in. The string is case-insensitive.

    • Specify the minimum version as the MinVersion attribute of the Set element in the add-in manifest. Here's an example that sets the minimum required version of the Mailbox API to v1.1.

      <Requirements>
          <Sets>
              <Set Name="Mailbox" MinVersion="1.1" />
          </Sets>
      </Requirements>
      
  4. Specify version 1.1 of the add-in manifest schema, as shown in the following example.

    <?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">
    
Show:
© 2015 Microsoft