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 can be acquired from AppSource or sideloaded by end-users or administrators.
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.
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 are the ways that add-ins integrate with Outlook. The following are the ways this can be done.
Add-ins can declare buttons that appear in command surfaces across messages and appointments. For more information, see Add-in commands.
Add-ins can link off regular expression matches or detected entities in messages and appointments. For more information, see Contextual Outlook add-ins.
Entity-based contextual Outlook add-ins will be retired in Q2 of 2024. The work to retire this feature will start in May and continue until the end of June. After June, contextual add-ins will no longer be able to detect entities in mail items to perform tasks on them. The following APIs will also be retired.
To help minimize potential disruptions, the following will still be supported after entity-based contextual add-ins are retired.
- An alternative implementation of the Join Meeting button, which is activated by online meeting add-ins, is being developed. Once support for entity-based contextual add-ins ends, online meeting add-ins will automatically transition to the alternative implementation to activate the Join Meeting button.
- Regular expression rules will continue to be supported after entity-based contextual add-ins are retired. We recommend updating your contextual add-in to use regular expression rules as an alternative solution. For guidance on how to implement these rules, see Use regular expression activation rules to show an Outlook add-in.
For more information, see Retirement of entity-based contextual Outlook add-ins.
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.
- Add-ins now activate on IRM-protected items in Outlook on Windows (starting in Version 2009 (Build 13229.10000)), on Mac (starting in Version 16.77.827.0), and on the web. To turn on this capability, a tenant administrator must enable the
OBJMODELusage right by setting the Allow programmatic access custom policy option in Office. For further guidance, see Usage rights and descriptions.
- Starting in Outlook on Windows Version 1711 (Build 8711.1000) associated with a Microsoft 365 subscription, add-ins activate on digitally-signed messages.
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.
* 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.
Outlook add-ins are supported in Outlook on Windows, 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.