What are Microsoft Outlook Add-Ins and How do they Work?
What Platforms Does an Add-In Work On?
Outlook Add-Ins work with differing features on every version of Outlook from 2013 onwards. This includes Outlook on Android and iOS and Outlook on MacOS, as well as the web version of Office 365 and outlook.com. Outlook Add-Ins also have a limited feature set for Gmail accounts, but only when running on Outlook for MacOS!
Sophisticated Microsoft Outlook Add-Ins sometimes require access to advanced Add-In features such as SSO, EWS, Fallback Authentication etc. If your Add-In falls into this category, you may be thinking that you will only be able to release your Outlook Add-In on a small subset of the available platforms. For example, if you require SSO or Fallback Authentication, you may worry you can only release your Add-In on a few platforms (mobile, Office365, outlook.com).
However, with careful use of some of the properties exposed by the Outlook Add-In API and Office context, we explain how you may well be able to provide a graceful fallback experience on platforms that don’t support more advanced Add-In features.
Understanding Support Levels
Understanding the various support levels for features in an Outlook Add-In is complicated. The information required for a good understanding is spread across multiple web pages in the Add-In documentation.
The platform features covered here are:
- SSO Support (via Identity 1.3)
- Requirement Set
- EWS API Support
|Platform||Client||Identity API 1.3 (SSO) Supported||Max Supported Outlook API Requirement Set||EWS Support||context.platform||accountType|
|iOS||App (Office 365)||No||1.5||No||Yes||No|
|Android||App (Office 365)||No||1.5||No||Yes||No|
|Web||Outlook (Old UI) for Exchange on premise||No||1.6||Yes||Yes||Yes|
|Windows||Desktop 2019 volume license||No||1.7||Yes||Yes||Yes|
|Mac||Desktop (office 365)||No||1.7 (new UI)||Yes||Yes||Yes|
|Windows||Desktop 2019 retail||No||1.8||Yes||Yes||Yes|
|Mac||Desktop (office 365)||Yes (16.40 or later)||1.8 (old UI)||Yes||Yes||Yes|
|Web||Outlook (New UI) for Office 365||Yes||1.9||Yes||Yes||Yes|
|Web||Outlook (New UI) for Outlook.com||No||1.9||Yes||Yes||Yes|
|Windows||Desktop (Office 365)||Yes (2800 or later)||1.9||Yes||Yes||Yes|
Fallback Strategies and Support Levels Explained
· Client and Platform
The “Client” in the table above refers to the Outlook application that is running the Add-In. For example, “Desktop 2016” refers to the version of MS Office 2016 that is purchased through a single perpetual license fee. Desktop (Office 365) refers to the MS Office version downloaded and installed as part of an Office 365 subscription.
The Platform refers to the operating system that the Client is installed on.
Single Sign-On (SSO) support is provided with the Identity API 1.3 and above. It should be noted that you must provide a fallback login mechanism if you want to submit your Add-In to AppSource.
· Max Supported Outlook API Requirement Set
· EWS Support
This indicates if the target Client and Platform support the EWS API. Obviously, you will need to have a correctly configured Exchange instance with the EWS API properly exposed in order to use this API. Generally, we avoid EWS and rely on Graph API instead, as few clients expose the EWS API, and more and more are hosting their email platform using Office 365.
· context.platform and accountType
For complex Outlook Add-Ins of the type we typically build, these two properties are essential! They are in full:
“platform” can have one of these values:
|OfficeOnline||Office on the web (i.e. a web browser)|
|Universal||WinRT – you probably aren’t using this!|
accountType can have these values:
|office365||Microsoft 365 work or school|
The big surprise here is the support for Gmail. This is vastly under-documented by Microsoft, and even the press release announcing it has vanished from the MS web site. Our experiments have shown that Gmail accounts only appear to work for Add-Ins on the Mac platform, although we cannot find this documented anywhere!
You should be aware that accountType is ONLY supported in Outlook API Requirement Set 1.6 and above!
Summarising Outlook Add-In Fallback Strategies
The combination of platform and accountType (in association with other information) is powerful.
For example, if you wish to determine if “fallback authentication” is available, the condition would be (in pseudo-code):
var maxApi = getMaxAPI(); // A simple custom function we use!
var platform = Office.context.diagnostics.platform;
var accountType = maxApi >= 1.6 ? Office.context.mailbox.userProfile.accountType : null;
var supportsFallback = platform == Office.PlatformType.Android ||
platform == Office.PlatformType.iOS ||
accountType == “office365” ||
accountType == “outlookCom”;
A similar pseudocode could be produced to determine if the platform / accountType supports SSO.
It’s also worth pointing out that as accountType was not introduced until Requirement Set 1.6, it is impossible to determine the accountType for Desktop 2013 and 2016 as they are at Requirement Set 1.4.
Why is this Useful?
We make extensive use of this kind of information in our Microsoft Outlook Add-Ins to provide graceful fallback. For example, there may be an Add-In feature that needs access to attachments. This means that the Add-In will need to use the Graph API on the server-side. For this, we would need to carry out some fancy coding with App Registrations, token exchange etc. This means that we will need to know if our platform/accountType combination supports SSO or Fallback Authentication, which we can do as described above.
Once we have determined this, we can dynamically toggle the attachments related features of the Add-In on and off. This ensures that we can provide our Add-In on the widest possible range of platforms, and where some features are not available on certain platforms, we can dynamically toggle those features on and off.
Click below to view the next chapter which looks at Add-Ins and Gmail capability in more detail.