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:

  • platform
  • accountType
  • SSO Support (via Identity 1.3)
  • Requirement Set
  • EWS API Support
PlatformClientIdentity API 1.3 (SSO) SupportedMax Supported Outlook API Requirement SetEWS Supportcontext.platformaccountType
WindowsDesktop 2016No1.4YesYesNo
WindowsDesktop 2013No1.4YesYesNo
iOSApp (Office 365)No1.5NoYesNo
AndroidApp (Office 365)No1.5NoYesNo
WebOutlook (Old UI) for Exchange on premiseNo1.6YesYesYes
MacDesktop 2019No1.6YesYesYes
MacDesktop 2016No1.6YesYesYes
WindowsDesktop 2019 volume licenseNo1.7YesYesYes
MacDesktop (office 365)No1.7 (new UI)YesYesYes
WindowsDesktop 2019 retailNo1.8YesYesYes
MacDesktop (office 365)Yes (16.40 or later)1.8 (old UI)YesYesYes
WebOutlook (New UI) for Office 365Yes1.9YesYesYes
WebOutlook (New UI) for Outlook.comNo1.9YesYesYes
WindowsDesktop (Office 365)Yes (2800 or later)1.9YesYesYes

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.

· 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 max Support API Requirement Set for the Outlook Javascript API.

· 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:

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

“platform” can have one of these values:

Platform ValueExplanation
Android          
iOS      
Mac     
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

Gmail

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.

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 [email protected] Practitioner. Outside the office, Nick is a professional scuba diver and he holds the rank of Black Belt 5th Dan in Karate.