Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All

Specify the APIs your mail app for Outlook requires

apps for Office

Specify the version of the apps for Office platform that includes the features and functionality that you need for your mail app.

Last modified: June 16, 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 apps for Office platform means for mail apps
Define the version of the apps for Office platform
Additional resources

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

For mail apps, you specify:

  • The version of the app 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 app must use manifest schema version 1.1. If have an app that uses version 1.0, see Update the manifest of a mail app 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 app. The desired version of office.js is the version that supports the APIs used to implement all the optional features of your app. This might be the same as the minimum required version.

When the desired version is different from the minimum required version, your app might be installed and activated on a host that doesn't support all the elements your app needs. Determine whether the user's Exchange and Outlook versions support the APIs your app requires. If those APIs aren’t supported, you'll need conditional code that keeps your app working. For information about how to write conditional code, see Check host application support for specific API members at runtime.

For mail apps, you must specify the "Mailbox" requirement set in the manifest. Specify the minimum required version of the APIs your app uses in this requirement set in the MinVersion attribute of the Set element. For example, if your app 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/dn482463#bk_history section of an API reference topic.

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

To define the version of the apps for Office platform that your mail app requires:

  1. Decide on a scenario for your mail app and identify the features that the mail app 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 app, 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/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 app. The string is case-insensitive.

    • Specify the minimum version as the MinVersion attribute of the Set element in the app 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 app 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