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.

Requirement sets supported by Exchange servers and Outlook clients

In this section, we note the range of requirement sets supported by Exchange server and Outlook clients.

Important

If your target Exchange server and Outlook client support different requirement sets, then you're restricted to the lower requirement set range. For example, if an add-in is running in Outlook 2016 on Mac (highest requirement set: 1.6) against Exchange 2013 (highest requirement set: 1.1), your add-in is limited to requirement set 1.1.

Exchange server support

The following servers support Outlook add-ins.

Product Major Exchange version Supported API requirement sets
Exchange Online Latest build 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8
Exchange on-premises 2019 1.1, 1.2, 1.3, 1.4, 1.5
2016 1.1, 1.2, 1.3, 1.4, 1.5
2013 1.1

Outlook client support

Add-ins are supported in Outlook on the following platforms.

Platform Major Office/Outlook version Subscription or one-time purchase? Supported API requirement sets
Windows Latest builds Office 365 subscription 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8
2019 one-time purchase 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7
2016 one-time purchase 1.1, 1.2, 1.3, 1.4
2013 one-time purchase 1.1, 1.2, 1.3, 1.4
Mac Latest builds Office 365 subscription 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8
2019 one-time purchase 1.1, 1.2, 1.3, 1.4, 1.5, 1.6
2016 one-time purchase 1.1, 1.2, 1.3, 1.4, 1.5, 1.6
iOS Latest builds Office 365 subscription 1.1, 1.2, 1.3, 1.4, 1.5
Android Latest builds Office 365 subscription 1.1, 1.2, 1.3, 1.4, 1.5
Web browser modern Exchange Online: Office 365 subscription, Outlook.com 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8
classic Exchange on-premises 1.1, 1.2, 1.3, 1.4, 1.5, 1.6

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.