Outlook add-ins overview

Outlook add-ins are integrations built by third parties into Outlook by using our web-based platform. Outlook add-ins have three key aspects:

  • The same add-in and business logic works across desktop (Outlook on Windows and Mac), web (Microsoft 365 and Outlook.com), and mobile.
  • Outlook add-ins consist of a manifest, which describes how the add-in integrates into Outlook (for example, a button or a task pane), and JavaScript/HTML code, which makes up the UI and business logic of the add-in.
  • Outlook add-ins can be acquired from AppSource or sideloaded by end-users or administrators.

Outlook add-ins are different from COM or VSTO add-ins, which are older integrations specific to Outlook running on Windows. Unlike COM add-ins, Outlook add-ins don't have any code physically installed on the user's device or Outlook client. For an Outlook add-in, Outlook reads the manifest and hooks up the specified controls in the UI, and then loads the JavaScript and HTML. The web components all run in the context of a browser or webview control in a sandbox.

Important

COM and VSTO add-ins aren't supported in the new Outlook on Windows that's currently in preview. These add-ins are still supported in the classic Outlook on Windows desktop client. To learn more, see Develop Outlook add-ins for new Outlook on Windows (preview).

The Outlook items that support add-ins include email messages, meeting requests, responses and cancellations, and appointments. Each Outlook add-in defines the context in which it is available, including the types of items and if the user is reading or composing an item.

Note

If you plan to publish your add-in to AppSource and make it available within the Office experience, make sure that you conform to the Commercial marketplace certification policies. For example, to pass validation, your add-in must work across all platforms that support the methods that you define (for more information, see section 1120.3 and the Office Add-in application and availability page).

Extension points

Extension points are the ways that add-ins integrate with Outlook. The following are the ways this can be done.

Mailbox items available to add-ins

Outlook add-ins activate when the user is composing or reading a message or appointment, but not other item types. However, add-ins are not activated if the current message item, in a compose or read form, is one of the following:

  • Protected by Information Rights Management (IRM) or encrypted in other ways for protection and accessed from Outlook on mobile devices. A digitally-signed message is an example since digital signing relies on one of these mechanisms. To learn more about IRM support in Outlook add-ins, see Mail items protected by IRM.

  • An IRM-protected mail item with a sensitivity label that has the Allow programmatic access custom policy option set to false. To learn more about IRM support in Outlook add-ins, see Mail items protected by IRM.

  • A delivery report or notification that has the message class IPM.Report.*, including delivery and Non-Delivery Report (NDR) reports, and read, non-read, and delay notifications.

  • A .msg or .eml file which is an attachment to another message.

  • A .msg or .eml file opened from the file system.

  • In a group mailbox, in a shared mailbox*, in another user's mailbox*, in an archive mailbox, or in a public folder.

    Important

    * Support for delegate access scenarios (for example, folders shared from another user's mailbox) was introduced in requirement set 1.8, while shared mailbox support was introduced in requirement set 1.13. To learn more, see Enable shared folders and shared mailbox scenarios.

  • Using a custom form.

  • Created through Simple MAPI. Simple MAPI is used when an Office user creates or sends an email from an Office application on Windows while Outlook is closed. For example, a user can create an Outlook email while working in Word which triggers an Outlook compose window without launching the full Outlook application. If, however, Outlook is already running when the user creates the email from Word, that isn't a Simple MAPI scenario so Outlook add-ins work in the compose form as long as other activation requirements are met.

In general, Outlook can activate add-ins in read form for items in the Sent Items folder, with the exception of add-ins that activate based on string matches of well-known entities. For more information about the reasons behind this, see Support for well-known entities.

Currently, there are additional considerations when designing and implementing add-ins for mobile clients. To learn more, see Add support for add-in commands in Outlook on mobile devices.

Mail items protected by IRM

Outlook add-ins activate on IRM-protected mail items when the item is accessed from the following supported clients.

  • Outlook on Windows starting in Version 2009 (Build 13229.10000)

    Note

    Digital signing relies on protection mechanisms, such as IRM. Starting in Outlook on Windows Version 1711 (Build 8711.1000) associated with a Microsoft 365 subscription, add-ins activate on digitally-signed messages.

  • Outlook on Mac starting in Version 16.77.827.0

  • Outlook on the web

  • new Outlook on Windows (preview)

However, add-ins won't activate on IRM-protected items when:

  • The IRM-protected item is accessed from Outlook on mobile devices.
  • The IRM-protected item has a sensitivity label with the Allow programmatic access custom policy option set to false. For more information on custom policy options, see Usage rights and descriptions.

Supported clients

Outlook add-ins are supported in Outlook on Windows (classic and new (preview)), Outlook on Mac, Outlook on the web, Outlook on iOS, Outlook on Android, and Outlook.com. Not all of the newest features are supported in all clients at the same time. For details about feature support on clients and servers, see Requirement sets supported by Exchange servers and Outlook clients and articles specific to those features.

Get started building Outlook add-ins

To get started building Outlook add-ins, try the following:

  • Quick start - Build a simple task pane.
  • Tutorial - Learn how to create an add-in that inserts GitHub gists into a new message.

See also