Introduction into Outlook Addin development

Outlook Addins are extensions to the Microsoft Outlook Client – both the desktop and the web client. Both are HTML/JavaScript applications – as are the addins. Addins are small web applications – HTML, CSS and JavaScrpipt – that run in an IFRAME next to the main Outlook client window – for reading or editing mail messages or calendar appointments. The JavaScript code in the addin can make use of the Microsoft Office JavaScript API to interact with the message or appointment.

In the GitHub Repository, you will find the materials – sources and hands on instructions – to get going step by step with addins and the Office JavaScript API. You will be able to navigate some of the stumbling blocks that I ran into as I tried to work out how to create my ultimate addin: a mail merge alternative to send personalized emails to large number of recipients (from a comma separated list of recipients and their properties). I did get the addin working (see: ManyMail – an addin that allows you to send a personalized email to many recipients, based on placeholders in the mail message (subject and body) and a CSV dataset with values for each recipient) but it was not easy and straightforward.

The addins discussed in this workshop:

• Hello World Addin – your first addin: it shows a sidepane with a button when you are editing an email; when you press the button, the text Hello World is inserted at the position of the cursor
• A simple variation on that theme: The Image Inserter Addin – It acts on a message that is being composed in the message editor. When the Addin is activated, it will cause an image – and a very pretty one! – to be inserted in the message under construction at the position of the cursor.
  
• Event Manager – This addin allows me to collect details about the positive, tentative and negative responses to an invitation to an appointment. When the button is clicked for the addin, the taskpane is shown with details for the appointment. The taskpane also contains a button that when pressed will cause the details for the RSVPs to be copied to the clipboard.
  
• Email Property Retriever – simple addin that allows you to fetch some properties of the email open in reading mode in the taskpane. Demonstrates very simple interaction through Office JS API regarding an mail message
• RSVP Handler – an addin that is available when looking at an RSVP to an appointment you have organized. The addin allows you to write details for this RSVP to local storage and to inspect the totals collected in local storage for this appointment. These totals can be displayed and copied
  
  
  

• ManyMail – an addin that allows you to send a personalized email to many recipients, based on placeholders in the mail message (subject and body) and a CSV dataset with values for each recipient.

There are some things regarding addin development you need to be aware of:

• elements of an addin: an addin at the lvery least contains a manifest file – that defines the name, the conditions under which the addin is active. the required/used permissions and the files that make up the addins UI and logic . It usually comes with one or more HTML (and possibly associated JavaScript and/or CSS files) and icon files (to show in the ribbon and addin menu and management page.
• the Office JavaScript API is for client side interaction with mail messages or appointments; to use the Microsoft Graph API to learn about contacts, appointment status or to send emails, the addin needs to be registered using Azure portal App Registration – and you need to have the permission to do so (in my company’s Microsoft tenant, I did not have that permission). The Office JS API does not support sending an email! (to get my ManyMail bulk mail merge addin to work, I have cheated a little: a small piece of JavaScript locates the HTML button element that the user presses to send the mail, and it programmatically does the same)
• addins are described by a manifest.xml file that needs to be uploaded to https://aka.ms/olksideload – when you go to that URL, the Outlook Web Client will open with a dialog to manage addins; this is where the manifest.xml file is to be uploaded
  
• Microsoft discusses a second manifest file format – a universal JSON based manifest; however, the Manage Addins dialog does not support that format
• To remove an addin (also from your local desktop client), you also go to the URL , open the Manage Addins page and through the ellipses (three little dots) on the addin, you can remove it (this too took me some time to figure out):
  
  
• Many things seem to be in flux, besides this manifest file format. The Office API, the EWS Exchange Web Services that seem to go away as well, replace with the Graph API, the Outlook REST Services  that are deprecated and are removed and the “old” Windows desktop client that is replaced by the “new” one – with currently less functionality. Between these different states and versions I could not always get things to work according to the documentation and certainly not in all three Outlook editions (Web, Desktop New, Desktop Old): they do not all work the same and treat the addin configuration the same. My main frustration was met Appointment details: in the old desktop version, I can get the RSVP details from the people I have invited in an appointment, in the new desktop version I have not been able to find a way to get hold of that data.
• The manifest,.xml file is not easy to master; it has the extension point element that is used to instruct Outlook when to make the addin available; I find it unintuitive and it feels it is not consistent across Outlook incarnations. Having an addin shown for inspecting an appointment for example (and getting the details for the appointment) did not go well at all. The file is supposed to be able to handle multiple extension point elements – but when I tried to load the file with these elements, it got rejected (no error message)
• The Addin (and the Outlook client itself) are simply HTML/JavaScript web applications – you can open browser dev tools (Ctrl+Shift+i) and inspect the code and debug it too (when running in the web client at least). This can be very helpful.
• Addins can be consumed from Microsoft AppSource (publicly) or Microsoft 365 admin center (within organization)- after a formal deployment – or they can be consumed from a web server, such as a local one (during development) and GitHub Pages for production deployment.
• For development of an addin, Microsoft provides several npm modules that make life quite easy. Assuming you already have VS Code and a current version of Node, install the latest version of Yeoman and the Yeoman generator for Office Add-ins. (npm install -g yo generator-officenpm install -g yo generator-office) . Next, you can run the addin generator to create a skaffold addin that you can fine tune: (yo office).
  See this document for instructions on these steps.
• Note: the generator does not generate the <script> tag in taskpane.html for including the taskpane.js file. During development that does not cause any issues. However, once you publish the addin to GitHub Pages, all of a suddent this lacking <SCRIPT> tag causes the addin to fail at runtime. As you might guess, it took me mighty long time to figure this one out
• An Addin runs in an IFRAME. It cannot directly interact with the standard UI elements. A trick I have used for the implementation of the ManyMail addin (only works in the web client when running in Chrome or Edge): use a browser extension that injects JavaScript into the main Outlook document. This snippet of code recognizes a new mail composition window when it contains a marker code,. It will remove the marker, locate the Send button and activate it. This will automatically send the email that the addin has created.
  
  

Resources

GitHub Repository – https://github.com/lucasjellema/outlook-addin 

Outlook JavaScript API – https://learn.microsoft.com/en-us/javascript/api/outlook

Build your first addin – https://learn.microsoft.com/en-us/office/dev/add-ins/quickstarts/outlook-quickstart?tabs=yeomangenerator

Scriptlab – https://learn.microsoft.com/en-us/office/dev/add-ins/overview/explore-with-script-lab

Tutorial: Build a message compose Outlook add-in – https://learn.microsoft.com/en-us/office/dev/add-ins/tutorials/outlook-tutorial?tabs=jsonmanifest

Tutorial: Use regular expression activation rules to show an Outlook add-in – check body of email for specific patterns and when found, turn text into link that opens addin when clicked. https://learn.microsoft.com/en-us/office/dev/add-ins/outlook/use-regular-expressions-to-show-an-outlook-add-in

And on Activation Rules: https://learn.microsoft.com/en-us/office/dev/add-ins/outlook/activation-rules