What Are Microsoft Outlook Add-Ins and How Do They Work?

Microsoft Add-In Platforms, Fallback Strategies and Support Levels

An Outlook Add-In is a piece of software that runs inside Microsoft Outlook. They’re typically used to provide a limited but handy set of features when a user is viewing or composing an email. In this blog, we’re looking at feedback strategies for Microsoft add-ins and the levels of support on different platforms.

You can learn more about what Microsoft Outlook add-ins are and what they can do on our previous post.

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, iOS and 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.

Fallback Strategies and Support Levels Explained

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, you may well be able to provide a graceful fallback experience on platforms that don’t support more advanced Add-In features.

· context.platform and accountType

For complex Outlook Add-Ins of the type we typically build, these two properties are essential! They are in full:

• Office.context.diagnostics.platform
• Office.context.mailbox.userProfile.accountType

• “platform” can have one of these values:

• accountType can have these values:

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 Microsoft website. 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.

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 in this table are:

• Whether or not SSO is available for that client (as part of the Identity API 1.3)
• The maximum support requirement set for the Mailbox API
• If EWS support is available
• If Graph API support is available

Learn about each of these values in more detail below the table.

Platform Feature Glossary

• Client and Platform

The ‘client’ 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 on which the client is installed.

• SSO

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

This is simply the maximum support API requirement set for the Outlook Javascript API.

• EWS Support

This indicates if the target client and platform support the EWS API. Of course, 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; few clients now expose the EWS API, and more and more are hosting their email platform using Office 365.

Other Key Points

There are a few other things to keep in mind as well:

1. If you are implementing Single Sign-On (SSO) for your Outlook Add-In, you will also need to implement fallback authentication. See Microsoft’s guide to enabling SSO for more information.
2. Mobile Clients for Outlook only support the MessageRead interface.
3. Support for the Requirement Set 1.3 was added to Outlook 2013 in the December 8^th 2015 update, and support for 1.4 was added in the September 13^th 2016 update. Make sure you install these updates (if you’re crazy enough to support Outlook 2013!).
4. Support for the Requirement Set 1.4 for Outlook 2016 was added in the July 3^rd 2018 update. Make sure you install this update.

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, and we will need to know if our platform/accountType combination supports SSO or Fallback Authentication.

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. Where some features are not available on certain platforms, we can dynamically toggle those features on and off.

For more information on Microsoft Office Add-Ins, please take a look at the other posts in this series. Alternatively, please contact us today to find out how we can help you with your WOPI integration.