Edit

Outlook JavaScript API requirement sets

  • Article

Outlook add-ins declare what API versions they require in their manifest. The markup varies depending on whether you're using the XML manifest format or the unified manifest for Microsoft 365.

The API version is specified by the "extensions.requirements.capabilities" property. Set the "capabilities.name" property to "Mailbox" and the "capabilities.minVersion" property 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.

"extensions": [
{
  "requirements": {
    "capabilities": [
      {
        "name": "Mailbox", "minVersion": "1.1"
      }
    ]
  },
  ...
}

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 in which Outlook client the add-in will appear. 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

Although Outlook on Android and on iOS support up to requirement set 1.5, your mobile add-in can now implement some APIs from later requirement sets. For more information on which APIs are supported in Outlook mobile, see Outlook JavaScript APIs supported in Outlook on mobile devices.

Use 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.
}

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.

Choose 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 2019 on Windows (highest requirement set: 1.6) against Exchange 2016 (highest requirement set: 1.5), your add-in may be limited to requirement set 1.5.

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, 1.13
IdentityAPI 1.31
Exchange on-premises2 2019 1.1, 1.2, 1.3, 1.4, 1.5
2016 1.1, 1.2, 1.3, 1.4, 1.5

Note

1 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.

2 Even if an add-in implements features from requirement sets not supported in an Exchange on-premises environment, it can still be added to an Outlook client as long as the requirement set specified in its manifest aligns with those supported by Exchange on-premises. However, an implemented feature will only work if the Outlook client in which the add-in is installed supports the minimum requirement set needed by a feature. To determine the requirement sets supported by varying Outlook clients, see Outlook client support. We recommend supplementing this with the documentation on the specific feature for any exceptions.

Outlook client support

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

Platform Major Office/Outlook version Supported API requirement sets
Web browser1 2 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, 1.13
IdentityAPI 1.33
classic Outlook UI when connected to
Exchange on-premises		 1.1, 1.2, 1.3, 1.4, 1.5, 1.6
Windows new Outlook on Windows (preview) 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 1.10, 1.11, 1.12, 1.13
IdentityAPI 1.33
  • Microsoft 365 subscription
  • retail perpetual
 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.84, 1.94, 1.104, 1.114, 1.124, 1.134
IdentityAPI 1.33
OpenBrowserWindowApi 1.1
volume-licensed perpetual Outlook 2021 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.84, 1.94
IdentityAPI 1.33
OpenBrowserWindowApi 1.1
volume-licensed perpetual Outlook 2019 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7
volume-licensed perpetual Outlook 2016 1.1, 1.2, 1.3, 1.45
Mac new UI6 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 1.10, 1.11, 1.12, 1.13
IdentityAPI 1.33
OpenBrowserWindowApi 1.1
classic UI 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8
IdentityAPI 1.33
OpenBrowserWindowApi 1.1
Android1 7 8 subscription 1.1, 1.2, 1.3, 1.4, 1.5
iOS1 7 8 subscription 1.1, 1.2, 1.3, 1.4, 1.5

Note

1 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.

2 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.

3 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.

4 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).
  • Support for 1.13 is available from Version 2304 (Build 16327.20248).

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.

5 Support for 1.4 in volume-licensed perpetual Outlook 2016 was added as part of the July 3, 2018, update for Office 2016 (KB4022223).

6 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.

7 Currently, there are additional considerations when designing and implementing add-ins for mobile clients. For more details, see code considerations when adding support for add-in commands in Outlook on mobile devices.

8 Although Outlook on Android and on iOS support up to requirement set 1.5, your mobile add-in can now implement some APIs from later requirement sets. For more information on which APIs are supported in Outlook mobile, see Outlook JavaScript APIs supported in Outlook on mobile devices.

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.

Reference the Office JavaScript API production library

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 on how to use preview APIs, see Test preview APIs.

Test 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.