Outlook add-in APIs

To use APIs in your Outlook add-in, you must specify the location of the Office.js library, the requirement set, the schema, and the permissions. You'll primarily use the Office JavaScript APIs exposed through the Mailbox object.

Office.js library

To interact with the Outlook add-in API, you need to use the JavaScript APIs in Office.js. The CDN for the library is https://appsforoffice.microsoft.com/lib/1/hosted/Office.js. Add-ins submitted to AppSource must reference Office.js by this CDN; they can't use a local reference.

Reference the CDN in a <script> tag in the <head> tag of the web page (.html, .aspx, or .php file) that implements the UI of your add-in.

<script src="https://appsforoffice.microsoft.com/lib/1/hosted/Office.js" type="text/javascript"></script>

As we add new APIs, the URL to Office.js will stay the same. We will change the version in the URL only if we break an existing API behavior.


When developing an add-in for any Office host application, reference the Office JavaScript API from inside the <head> section of the page. This ensures that the API is fully initialized prior to any body elements. Office hosts require that add-ins initialize within 5 seconds of activation. Crossing this threshold results in the add-in being declared unresponsive and an error message is displayed to the user.

Requirement sets

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

To control which Outlook clients the add-in appears in, specify a minimum requirement set version in the manifest. For example, if you specify requirement set version 1.3, the add-in will not show up in any Outlook client that doesn't support a minimum version of 1.3.

Specifying a requirement set doesn't limit your add-in to the APIs in that version. If the add-in specifies requirement set v1.1 but is running in an Outlook client that supports v1.3, the add-in can still use v1.3 APIs. The requirement set only controls which Outlook clients the add-in appears in.

To check the availability of any APIs from a requirement set greater than the one specified in the manifest, you can use standard JavaScript:

if (item.somePropertyOrFunction) {


These checks are not needed for any APIs that are in the requirement set version specified in the manifest.

Specify the minimum requirement set that supports the critical set of APIs for your scenario, without which features of your add-in won't work. You specify the requirement set in the manifest in the <Requirements> element. For more information, see Outlook add-in manifests and Understanding Outlook API requirement sets.

The <Methods> element doesn't apply to Outlook add-ins, so you can't declare support for specific methods.


Your add-in requires the appropriate permissions to use the APIs that it needs. There are four levels of permissions. For more details, see Understanding Outlook add-in permissions.

Permission level Description
Restricted Allows use of entities but not regular expressions.
Read item In addition to what is allowed in Restricted, it allows:
  • regular expressions
  • Outlook add-in API read access
  • getting the item properties and the callback token
Read/write In addition to what is allowed in Read item, it allows:
  • full Outlook add-in API access except makeEwsRequestAsync
  • setting the item properties
Read/write mailbox In addition to what is allowed in Read/write, it allows:

In general, you should specify the minimum permission needed for your add-in. Permissions are declared in the <Permissions> element in the manifest. For more information, see Outlook add-in manifests. For information about security issues, see Privacy and security for Office Add-ins.

Mailbox object

Outlook add-ins primarily use the APIs exposed through the Mailbox object. To access the objects and members specifically for use in Outlook add-ins, such as the Item object, you use the mailbox property of the Context object to access the Mailbox object, as shown in the following line of code.

// Access the Item object.
var item = Office.context.mailbox.item;

Additionally, Outlook add-ins can use the following objects:

  • Office object: for initialization.

  • Context object: for access to content and display language properties.

  • RoamingSettings object: for saving Outlook add-in-specific custom settings to the user's mailbox where the add-in is installed.

For information about using the Outlook JavaScript API, see Outlook add-ins.

See also