Making your Outlook Add-in contextual

In this article I will demonstrate how to make an Outlook Add-in appear only on certain words in an email.


In previous articles we have looked at creating an Outlook Add-in and then how it works. Other than only being a sample app, this Add-in now appears on every email. What would be much more user friendly would be to make sure it only appear contextually, say if a word was in the body of an email for example.

In this article we are going to make the example Add-in only appear in emails with the word “Websockets” in it.

The XML Manifest

If we look at the properties of the napa dev console (the spanner on the left)


We can see that there are a number of options for the “read form”


At the top we can see “Edit read form XML” which is the manifest for the application. What we are looking at above is the visual representation of that XML file.


Looking at the Use regular expression activation rules to show a mail add-in in Outlook article we can find an example of a rule which check through the body of the email as plain text

<Rule xsi:type=”ItemHasRegularExpressionMatch”

But in my example I am going to look for the words Websockets and make sure that ignorecase is true (websockets or WebSOckEts would work)

<Rule xsi:type=”ItemHasRegularExpressionMatch”

I inserted the XML snippet above *inside* of the XML example code shown


and if you look at the non-XML version of the Read Form properties, you can see how this change is reflected


Running the application

If we look at the sample sample email as before – we will now no longer see any Marky Websockets Add-in


But if we find a new email with the word websockets inside it – we can see that it is contextually highlighted


Clicking on the word itself then triggers the sample Add-in to run



In this article we have looked at how we can simply add an Add-in contextually to the body of an email.





How does the sample Outlook Add-in work?

In this article I will describe how the out of the box Outlook Add-in created in the previous article works.


In the previous article I showed how we can create an outlook Add-in, out of the box in less than 30 minutes. In this article we will take a look at how the Add-in actually works. That will in turn allow us to create our own in the future.

The Add-in

The Add-in itself is build up of a number of different parts which we will look at in turn. As this is a Read only app we will not look into the AppCompose folder as none of that is used in this Add-in



The Home.html represents the core of the Add-in and as you can see from the image – it is a complete HTML file


I say complete HTML file not to be facetious but to highlight what the Add-in really is. It is a self contained web application which has contextual information available from the parent Email. To better understand this, if we look at the way the Add-in is created within the interface, it should make more sense.

How the Add-in works (Nov 2015)

This is very likely to change over time, so contextually in November 2015 this is how it works. When you click on the Add-in link within the email an iframe is created within the website – the URL of that is the Add-in itself.

Looking at the DOM through Chrome Dev Tools we can see the Add-in and nothing else underneath it


When we click on the Marky Websockets (which will make sense in a later article) we can then see the new iFrame created


Clicking on the URL and opening the iFrame source in a new window reveals the basic building blocks of the Add-in|Web|16.00#&_xdm_Info=-1b68cff0_-3d7d1568_1446597857415|ocii1|


Viewing the source – it looks just like what we saw as home.html in the napa cloud app – cos it is !!!


Once we start to think of the Add-in as it’s own iframe running application we can start to envision all sorts of things we can do here….but more on that later.

Within home.html we load a number of files:


  • jQuery – nothing special there
  • office.js – this is the core of the Office Add-in technology, it creates the interface for the whole Add-in, both from the iframe creation to the iframe gaining the details from the parent.
  • App.js – this file creates some display functionality within the context of the app
  • Home.js – this is the file which creates the contents of the Add-in, within the context of the parent email (the actual Add-in code)


Well I would love to explain how this works – but it is rather obfuscated….. – I am going to have to piece this together over time – but for right now, let’s just go with – that is what makes all these unicorns and rainbows work……what I can tell is that it is loading a whole load of other libraries as well. It is not the only magic box.


Once the application is loaded within the app, this Immediately-Invoked Function Expression (IIFE) runs and creates the HTML for a notification popup, and appends it to the bottom of the Add-in within the iframe



Within the DOM of the iframe contents we can see the planted classname clearly. This notification will be called when we click on the name of the sender in the Add-in.



Home.js creates the interface from the Add-in to the information in the parent email.


This IIFE code comes in three sections:

  • Office.initialize
    • This is the code which triggers the office Add-in – it states that in the jQuery document.ready even call these two functions
  • app.initialize
    • This calls the initialize function() created within App.js
  • displayItemDetails()
    • This is a function which we will go into further


The “Office” namespace is used through all the Add-in codebase and precedes all the JavaScript API calls

In this function the code uses the Office.cast.item , which is actually superfluous. If you look at the link you will see that it is used within Visual Studio to achieve Intellisense for the real code which is “var item = Office.context.mailbox.item;”. The function can be simplified to the following


As you can see from the code above I have added a console.log(item) to see what we are getting here. Contained within the item object we can see other objects and the first one contains a lot of the information available within the JavaScript API


Further down the console.log we are able to see “functions” within the object


thus in our code – item.from actually calls the namespaced function within the item object, that then parses the object and collects the from information (see previous image)

Going back to the home.js code – this finall uses some jQuery to

  1. $(‘#from’).text(from.displayName);
    • Add the “displayName” to the id named from within home.html


  1. $(‘#from’).click(function () {
    app.showNotification(from.displayName, from.emailAddress);

    • When you click on the item within the from DIV the app.showNotification is called passing in the name and emailAddress




In this article we have taken a rather exhaustive look at exactly how the sample Outlook Add-in works. I believe that with a better understanding of how the underlying application functionality work, we are able to better harness it’s power in the future.

In the next article I will look at how to manipulate the contents of the sample and start to build something with purpose.


Creating your first O365 Outlook Add-in in less than 30 minutes

In this article I will demonstrate how use the napa cloud application development environment to create an Outlook Add-in.


That basis for this article can be found all over the Microsoft MSDN development website(s) but the main starting points are:

You will need to add the Napa Office dev tools to your dev site –

I have a dev site created within the PSC O365 environment and from there I was able to create a new app.

Creating a new App


I was directed to the site where I added a new app


Select to build an Mail add in, give it a name and then Create


The napa development IDE comes up. It contains the default of a sample app


Publish it, by clicking on the Go Arrow on the left


You will be asked to log into your dev site (and therefore your O365 account)


Clicking Continue will open your O365 account you will then see the Add in Immediately appear in all emails


Clicking on the Add-in will reveal it



In this article we have seen how we can create the basic simple Outlook Add-In, in less than 10 minutes of work. In future articles we will look at how it works and how you can modify it to do your evil bidding.