Docs API Reference

Overview of Outlook add-ins architecture and features

An Outlook add-in consists of an XML manifest and code (JavaScript and HTML). The manifest specifies the name and description of the add-in, as well as how the add-in integrates into Outlook. Using the manifest, developers can place buttons on command surfaces, link off regular expression matches and so on. The manifest also defines the URL that hosts the JavaScript and HTML code for the add-in.

When a user or administrator acquires an add-in, the add-in's manifest is saved to the user's mailbox or into the organization. When Outlook starts up, it loads all manifests the user has installed, processes them and sets up all the extension points for the add-in (for example, display buttons in command surfaces, run regular expression against currently selected message, and so forth). The user can now use the add-in.

When the user interacts with the add-in, the JavaScript and HTML files are loaded from the host location specified in the manifest.

Add-ins use the Office.js API to access the Outlook Add-in API and interact with Outlook.

Interaction of typical components when the user starts Outlook

Flow of events when starting Outlook mail app


As we evolve Outlook clients and the add-in platform and add new ways for add-ins to integrate, sometimes we're unable to implement a feature at the same time across all clients (Mac, Windows, web, mobile). To handle this situation, we version both the manifest and the APIs. In this way the platform supports backwards compatibility at all times, meaning that developers can build an add-in which works in a down-level way in older clients, but also lets you take advantage of new features in newer clients. You can read more about how versioning works in Outlook add-in manifests.

Outlook add-in features

Outlook add-ins offer many rich features that can be used to support various scenarios.

Feature Description
Contextual activation Outlook contextual add-ins can activate based on the following criteria:
Module extensions An Outlook module extension integrates your add-in with the Outlook navigation bar. For more information see Integrate your Outlook add-in with Outlook's navigation bar. Module extensions are only available in Outlook 2016 for Windows.
Add-in commands Outlook add-in commands provide ways to initiate specific add-in actions from the ribbon. They are only available for module extensions and add-ins that apply to all emails or events. For more information see Add-in commands for Outlook.
Roaming settings An Outlook add-in can save data that is specific to the user's mailbox that you can access in a subsequent Outlook session. For more information see Get and set add-in metadata for an Outlook add-in.
Custom properties An Outlook add-in can save data that is specific to an item in the user's mailbox that you can access in a subsequent Outlook session. For more information see Get and set add-in metadata for an Outlook add-in.
Getting attachments or the entire selected item A contextual Outlook add-in can access attachments and the entire selected item from the server-side. See the following:
  • Attachments - see Get attachments of an Outlook item from the server and [Add and remove attachments to an item in a compose form in Outlook]
  • Entire selected item - this is similar to using a callback token to get attachments. See the following:
    • mailbox.getCallbackTokenAsync method in Office.context.mailbox - Provides a callback token to identify the add-in's server side code for the Exchange Server.
    • item.itemId property in Office.context.mailbox - Identifies the item that the user is reading and that the server-side code is getting.
    • mailbox.ewsUrl property in Office.context.mailbox - Provides the EWS endpoint URL which, together with the callback token and item ID, the server-side code can use to access the GetItem EWS operation to get the entire item.
User profile A mail add-in can access the display name, email address, and time zone in the user's profile. For more information see the UserProfile object.

Get started building Outlook add-ins

To get started building Outlook add-ins, see Get Started with Outlook add-ins for Office 365 or Integrate your Outlook add-in with Outlook's navigation bar.

Additional resources

For concepts that are applicable to developing Office add-ins in general, see the following: