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:
Platform ValueExplanation
OfficeOnline Office on the web (i.e. a web browser)
PC      Windows PC
UniversalWinRT – you probably aren’t using this!

  • accountType can have these values:
AccountType ValueExplanation
enterpriseOn-premise exchange
gmailGmail account
office365Microsoft 365 work or school
outlookComOutlook.com account

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.

PlatformClientIdentity API 1.3 (SSO) SupportedMax Supported Outlook API Requirement SetEWS SupportOutlook REST API (via MS Graph) support
WindowsDesktop (Office 365) Build 2104+Yes1.1YesYes
WindowsDesktop (Office 365) Build < 2104Yes (2800 or later)1.9YesYes
WindowsDesktop 2021 retailYes1.9YesYes
WindowsDesktop 2019 retailNo1.8YesYes
WindowsDesktop 2019 volume licenseNo1.7YesYes
WindowsDesktop 2016No1.4YesYes
WindowsDesktop 2013No1.4YesYes
WebOutlook (New UI) for Office 365Yes1.1YesYes
WebOutlook (New UI) for Outlook.comNo1.1YesYes
WebOutlook (Old UI) for Exchange on premiseNo1.6YesYes
MacDesktop (office 365)Yes (16.40 or later)1.8 (old UI)YesYes
MacDesktop (office 365)No1.7 (new UI)YesYes
MacDesktop 2019No1.6YesYes
MacDesktop 2016No1.6YesYes
iOSApp (Office 365)No1.5NoYes
AndroidApp (Office 365)No1.5NoYes

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 8th 2015 update, and support for 1.4 was added in the September 13th 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 3rd 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.

Nick McKenna
Since 2004, Nick McKenna, BSc, MBCS Biography has been the CEO of McKenna Consultants. McKenna Consultants is a bespoke software development based in North Yorkshire, specialising in Cloud development, mobile App development, progressive web App development, systems integration and the Internet of Things development. Nick also holds a First Class Degree in Computer Science (BSc) and wrote his first computer program at the age of nine, on a BBC Micro Model B computer. For the last 21 years, Nick has been a professional computer programmer and software architecture. Nick’s technical expertise includes; Net Core, C#, Microsoft Azure, Asp.Net, RESTful web services, eProcurement, Swift, iOS mobile development, Java, Android mobile development, C++, Internet Of Things and more. In addition, Nick is experienced in Agile coaching, training and consultancy, applying modern Agile management techniques to marketing and running McKenna Consultants, as well as the development of software for clients. Nick is a Certified Enterprise Coach (Scrum Alliance), SAFe Program Consultant (SAI), Certified LeSS Practitioner (LeSS) and Certified Scrum@Scale Practitioner. Outside the office, Nick is a professional scuba diver and he holds the rank of Black Belt 5th Dan in Karate.