Outlook JavaScript API requirement sets

Outlook add-ins declare what API versions they require by using the Requirements element in their manifest. Outlook add-ins always include a Set element with a Name attribute set to Mailbox and a MinVersion attribute set to the minimum API requirement set that supports the add-in's scenarios.

For example, the following manifest snippet indicates a minimum requirement set of 1.1.

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

All Outlook APIs belong to the Mailbox requirement set. The Mailbox requirement set has versions, and each new set of APIs that we release belongs to a higher version of the set. Not all Outlook clients support the newest set of APIs, but if an Outlook client declares support for a requirement set, it supports all of the APIs in that requirement set.

Setting a minimum requirement set version in the manifest controls which Outlook client the add-in will appear in. If a client does not support the minimum requirement set, it does not load the add-in. For example, if requirement set version 1.3 is specified, this means the add-in will not show up in any Outlook client that doesn't support at least 1.3.

Note

To use APIs in any of the numbered requirement sets, you should reference the production library on the CDN (https://appsforoffice.microsoft.com/lib/1/hosted/office.js).

For information about using preview APIs, see the Using preview APIs section later in this article.

Using APIs from later requirement sets

Setting a requirement set does not limit the available APIs that the add-in can use. For example, if the add-in specifies requirement set "Mailbox 1.1", but it is running in an Outlook client which supports "Mailbox 1.3", the add-in can use APIs from requirement set "Mailbox 1.3".

To use a newer API, developers can check if a particular host supports the requirement set by doing the following.

if (Office.context.requirements.isSetSupported('Mailbox', '1.3')) {
  // Perform actions.
}
else {
  // Provide alternate flow/logic.
}

Alternatively, developers can check for the existence of a newer API by using standard JavaScript technique.

if (item.somePropertyOrFunction !== undefined) {
  // Use item.somePropertyOrFunction.
  item.somePropertyOrFunction;
}

No such checks are necessary for any APIs which are present in the requirement set version specified in the manifest.

Choosing a minimum requirement set

Developers should use the earliest requirement set that contains the critical set of APIs for their scenario, without which the add-in won't work.

Clients

The following clients support Outlook add-ins.

Client Supported API requirement sets
Outlook on Windows (connected to Office 365 subscription) 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7
Outlook 2019 on Windows (one-time purchase) 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7
Outlook 2016 on Windows (one-time purchase) 1.1, 1.2, 1.3, 1.4
Outlook 2013 on Windows (one-time purchase) 1.1, 1.2, 1.3, 1.4
Outlook on Mac (connected to Office 365 subscription) 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7
Outlook 2019 on Mac (one-time purchase) 1.1, 1.2, 1.3, 1.4, 1.5, 1.6
Outlook 2016 on Mac (one-time purchase) 1.1, 1.2, 1.3, 1.4, 1.5, 1.6
Outlook on iOS 1.1, 1.2, 1.3, 1.4, 1.5
Outlook on Android 1.1, 1.2, 1.3, 1.4, 1.5
Outlook on the web (modern) 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7
Outlook on the web (classic) 1.1, 1.2, 1.3, 1.4, 1.5, 1.6
Any Outlook client connected to Exchange 2019 on-premises 1.1, 1.2, 1.3, 1.4, 1.5
Any Outlook client connected to Exchange 2016 on-premises 1.1, 1.2, 1.3
Any Outlook client connected to Exchange 2013 on-premises 1.1

Note

Support for 1.3 in Outlook 2013 was added as part of the December 8, 2015, update for Outlook 2013 (KB3114349). Support for 1.4 in Outlook 2013 was added as part of the September 13, 2016, update for Outlook 2013 (KB3118280). Support for 1.4 in Outlook 2016 (MSI) was added as part of the July 3, 2018, update for Office 2016 (KB4022223).

Tip

You can distinguish between classic and modern Outlook in a web browser by checking your mailbox toolbar.

modern

partial screenshot of the modern Outlook toolbar

classic

partial screenshot of the classic Outlook toolbar

Using preview APIs

New Outlook JavaScript APIs are first introduced in "preview" and later become part of a specific, numbered requirement set after sufficient testing occurs and user feedback is acquired. To provide feedback about a preview API, please use the feedback mechanism at the end of the web page where the API is documented.

Note

Preview APIs are subject to change and are not intended for use in a production environment.

For more details about the preview APIs, see Outlook API Preview requirement set.