Edit

Outlook JavaScript API requirement sets

  • Article
  • 6 minutes to read

Outlook add-ins declare what API versions they require in their manifest. The markup varies depending on whether you are using the Teams manifest format (preview) or the XML manifest format.

The API version is specified by the Requirements element. 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, generally it supports all of the APIs in that requirement set (check the documentation on a specific API or feature for any exceptions).

Setting a minimum requirement set version in the manifest controls which Outlook client the add-in will appear in. If a client doesn't support the minimum requirement set, it doesn't 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 Office.js content delivery network (CDN).

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 doesn't limit the available APIs that the add-in can use. For example, if the add-in specifies requirement set "Mailbox 1.1", but it's 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 application supports the requirement set by doing the following:

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

Important

There is currently a bug where isSetSupported('Mailbox', '1.3') erroneously returns true in Outlook on the web against Exchange 2013. To learn more about the supported combinations of requirement sets, Exchange servers, and Outlook clients, see Requirement sets supported by Exchange servers and Outlook clients.

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

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

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. For details about server and client requirements for running Outlook add-ins, see Outlook add-ins requirements.

Important

If your target Exchange server and Outlook client support different requirement sets, then you may be 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 may be 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, 1.9, 1.10, 1.11, 1.12
IdentityAPI 1.3*
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

Note

* To require the Identity API set 1.3 in your Outlook add-in code, check if it's supported by calling isSetSupported('IdentityAPI', '1.3'). Declaring it in the Outlook add-in's manifest isn't supported. You can also determine if the API is supported by checking that it's not undefined. For further details, see Using APIs from later requirement sets.

Outlook client support

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

Platform Major Office/Outlook version Supported API requirement sets
Windows - Microsoft 365 subscription
- retail perpetual Outlook 2016 and later		 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.81, 1.91, 1.101, 1.111, 1.121
IdentityAPI 1.32
volume-licensed perpetual Outlook 2021 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.81, 1.91
IdentityAPI 1.32
volume-licensed perpetual Outlook 2019 1.1, 1.2, 1.3, 1.4, 1.5, 1.6
volume-licensed perpetual Outlook 2016 1.1, 1.2, 1.3, 1.43
perpetual Outlook 2013 1.1, 1.2, 1.33, 1.43
Mac classic UI 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8
IdentityAPI 1.32
new UI4 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 1.10, 1.11, 1.12
IdentityAPI 1.32
iOS5 6 subscription 1.1, 1.2, 1.3, 1.4, 1.5
Android5 6 subscription 1.1, 1.2, 1.3, 1.4, 1.5
Web browser5 7 modern Outlook UI when connected to
Exchange Online: subscription, Outlook.com		 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 1.10, 1.11, 1.12
IdentityAPI 1.32
classic Outlook UI when connected to
Exchange on-premises		 1.1, 1.2, 1.3, 1.4, 1.5, 1.6

Note

1 Version support for more recent requirement sets in Outlook on Windows with a Microsoft 365 subscription or a retail perpetual license as follows:

  • Support for 1.8 is available from Version 1910 (Build 12130.20272).
  • Support for 1.9 is available from Version 2008 (Build 13127.20296).
  • Support for 1.10 is available from Version 2104 (Build 13929.20296).
  • Support for 1.11 is available from Version 2110 (Build 14527.20226).
  • Support for 1.12 is available from Version 2206 (Build 15330.20196).

For more details according to your version, see the update history page for Office 2021 or Microsoft 365 and how to find your Office client version and update channel.

2 To require the Identity API set 1.3 in your Outlook add-in code, check if it's supported by calling isSetSupported('IdentityAPI', '1.3'). Declaring it in the Outlook add-in's manifest isn't supported. You can also determine if the API is supported by checking that it's not undefined. For further details, see Using APIs from later requirement sets.

3 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 volume-licensed perpetual Outlook 2016 was added as part of the July 3, 2018, update for Office 2016 (KB4022223).

4 Support for the new Mac UI is available from Outlook Version 16.38.506. For more information, see the Add-in support in Outlook on new Mac UI section.

5 Add-ins aren't supported in Outlook on Android, on iOS, and modern mobile web with on-premises Exchange accounts. Certain iOS devices still support add-ins when using on-premises Exchange accounts with classic Outlook on the web. For information about supported devices, see Requirements for running Office Add-ins.

6 Currently, there are additional considerations when designing and implementing add-ins for mobile clients. For example, the only supported mode is Message Read. For more details, see code considerations when adding support for add-in commands for Outlook Mobile.

7 Add-ins don't work in modern Outlook on the web on iPhone and Android smartphones. For information about supported devices, see Requirements for running Office Add-ins.

Tip

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

modern

The modern Outlook toolbar.

classic

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 aren't intended for use in a production environment.

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