Outlook JavaScript API requirement sets
Outlook add-ins declare what API versions they require in their manifest. The markup varies depending on whether you're using the add-in only 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, 1.14 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.
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 To learn about the minimum supported versions for recent requirement sets in classic Outlook on Windows with a Microsoft 365 subscription or a retail perpetual license, see Version support for requirement sets in classic Outlook on Windows.
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 Although classic Outlook on Mac doesn't support Mailbox requirement set 1.9, it does support the DialogApi 1.2 requirement set. For information on the minimum supported version and build, see Dialog API requirement sets.
8 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. 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
classic
Version support for requirement sets in classic Outlook on Windows
The following table lists version support for more recent Mailbox requirement sets in classic Outlook on Windows with a Microsoft 365 subscription or a retail perpetual license.
| Requirement set | Version |
|---|---|
| 1.8 | Version 1910 (Build 12130.20272) |
| 1.9 | Version 2008 (Build 13127.20296) |
| 1.10 | Version 2104 (Build 13929.20296) |
| 1.11 | Version 2110 (Build 14527.20226) |
| 1.12 | Version 2206 (Build 15330.20196) |
| 1.13 | Version 2304 (Build 16327.20248) |
| 1.14 | Version 2404 (Build 17530.15000) |
For more details about your client version, see the update history page for Microsoft 365 or Office 2024 and how to find your Office client version and update channel.
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.
Office Add-ins