Creating an Outlook Mail App in Visual Studio 2012

Posted on Friday, November 2nd, 2012 at 7:10 am by Ty Anderson.

It’s time to stop messing around and take the Office web app model for a spin. In this article, I’ll show you how to create a simple but useful Outlook Mail App that lets you attach notes to mail items. For this article, you need the following:

Creating the Outlook mail app project with Visual Studio 2012

The MailNotes app is built using one the new Apps for Office project templates. Let’s get started by completing these steps:

With Visual Studio 2012 open, select File > New Project from the main menu.
In the New Project dialog box, select the Templates > Office/SharePoint > Apps node.
Click the App for Office 2013 project template, name the project MailNotes, and click the OK button.
The Create App for Office dialog box will display. Select the Mail app in option and only select Email Message. Click Finishto create the project.

After creating the Outlook mail app project, Visual Studio will display the MailNotes.html file but let’s take a quick review of the main files in the project:

The structure of the mail app project in Visual Studio 2012

MailNotes.html: This file is a web page. It contains the HTML markup used to render the page to the user. It is the presentation layer and you can take advantage of web technologies to create a snazzy display.
MailNotes.js: This is a blank JavaScript file intended for custom business rules. MailNotes.html already has a reference to it. We will place our custom methods here./li>
MailNotes.xml: This is the application manifest. It includes information about your mail app (e.g. DisplayName) along with the rule definitions that specify the activation rules that cause the application to display. The default rule that specifies ItemType=Message is exactly what we need.

Clearly, there are more files but let’s cover them another day. We have plenty to do already!

Designing the Outlook mail app “panel”

The MailNotes app’s elegance is its simplicity. Anytime a user views a mail item, our mail app will display its button in Outlook 2013. When clicked, the MailNotes “panel” (I don’t know what else to call it) will become visible and display a text area and the button.

The MailNotes app's design

The Outlook user can input a brief note into the textarea and click the button to save their note. If successful, the MailNotes app displays a panel to let them know and provide that ever-elusive warm fuzzy feeling.

To implement this design, edit your <Body> tag in MailNotes.html so that matches the code in Listing 1.

Listing 1. The Body tag of MailNotes.html

<div id="Content">
    <input type="button" value="Save Note" onclick ="saveNote()" />
</div>
<div id="Note">
   <span id="statusMessage" style="background-color:#0072C6; color:white;" ></span>
   <br />
   <textarea id="MailNotes" rows="3" onblur="setbg('white')"
      onfocus="setbg('#FFFFFF');" >Enter your note here</textarea>
</div>

We now have a button labeled “Save Note”. This button will call a custom method (saveNote) when the user clicks it. The textarea will change background colors from white to gray depending on its focus (or lack thereof). The span is defined but will not display just yet. Already I’m liking using JavaScript.

Now, because I want to make the mail app’s panel look nice and match the new Outlook 2013 and Office 365 “Wave 15” themes, we need some CSS stylings. Nothing major. Just one little script (see Listing 2) that you need to add within the <Head> tag.

Listing 2. The custom style for the MailNotes panel

<style>
    body { background: #e3e3e3; }
    textarea {
        height: 120px;
        border: 3px solid #0072C6;
        padding: 5px;
        font-family: Tahoma, sans-serif;
        background:#cccccc
    }
</style>

This style snippet sets a few properties that will greatly enhance the user experience.

Adding JavaScript to the mail app

The custom code for our Outlook mail app handles the saving of a custom property to the current mail item. The custom property stores the note and saves it to Exchange. What we need is some code to write and read this property.

Let’s start by opening the MailApp.js file and adding the code from Listing 3.

Listing 3. The Initialize event and class objects

var _mailbox;
var _Item;
var _CustomProps;
 
Office.initialize = function () {
    _mailbox = Office.context.mailbox;
    _Item = _mailbox.item;
    _Item.loadCustomPropertiesAsync(loadCustomProps);
};

The initialize event is akin to a COM add-in’s StartUp event. It is the appropriate event for creating references the app will need later. In the case of MailNotes, we need references to the mailbox (_mailbox), the mail item (_Item), and the mail item’s custom properties collection (_CustomProps).

Okay fine. We have references now so let’s do something… like add the code from Listing 4.

Listing 4. The code for saving and loading custom properties

function saveNote() {
    var newPropValue = $('#MailNotes').text();
    setCustomProperty(newPropValue);
}
 
function setCustomProperty(propValue) {
    _CustomProps.set("mail_note", propValue);
    _CustomProps.saveAsync(saveCustomProps);
 
    $('#statusMessage').text("  :: NOTE SAVED ::  ");
    setbg("#cccccc");
}
 
// Callback method after saving custom properties.
function saveCustomProps(asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {        
    }
}
 
function loadCustomProps(obj) {
    _CustomProps = obj.value;
 
    if (_CustomProps.get("mail_note")) {
        var propValue = _CustomProps.get("mail_note");
        $('#MailNotes').text(propValue);
    }
}

These are the functions that will read and write the notes to the mail item:

SaveNote : The Save Note button calls this method to initiate the save process. Here, we grab the text from the MailNotes textarea then call setCustomProperty and pass the note text as a parameter.
setCustomPropety : This method uses the mail item’s custom properties collection to create custom property and save it. The save is done asynchronously which then calls.
SaveCustomProps as a callback method.
saveCustomProps : This method allows us to check the success or failure of the save process and respond accordingly. The mail app framework makes it easy for us to check via the asyncResult object.
loadCustomProps : This method will attempt to load the custom property that contains a mail note (mail_note). It first checks for the existence of the property and, if found, displays it in the MailNotes textarea.

There is one last function and Listing 5 contains its logic.

Listing 5. The setbg function

function setbg(color) {
    document.getElementById("MailNotes").style.background = color
}

This function uses the color parameter to change the background color of the MailNotes text area. We call it in the textarea’s onblur and onfocus events.

The MailNotes mail app in Outlook 2013 and Office 365

Let’s take our newly created mail app to Office 365 and Outlook 2013 for a test drive. With Visual Studio, loading the app into your Office 365 developer account is as easy as pressing F5… meaning, it is just what you expect. So go ahead and hit F5. The app will compile and you will be presented with the Connect to Exchange email account dialog box.

Connecting to the Exchange email account

Enter your credentials and click Connect. Visual Studio will take it from there by installing the app in and opening Outlook Web Access. You should be able to select an email and see the MailNotes panel.

The mail app in Office 365

Simply click it, add a note, and click the Save Note button.

Now open Outlook 2013 and navigate to your inbox. Click the mail and open the MailNotes panel.

The mail app in Outlook 2013

You should see the note you entered in Outlook Web Access. If you don’t, well, you did it wrong!

***
This was a simple (yet elegant) demo. The fact that now have a model for building a mail app once and have it run in Outlook 2013 desktop as well as Outlook 2013 Web Access is huge. Granted, we can’t do as much with the current JavaScript-based Office object model as we can with current Office development frameworks. But so what. Outlook mail apps provide a new toolset with new features that will prove to be quite useful in the right circumstances.

Available downloads:

This sample add-on was developed using Visual Studio 2012 with Apps for Office project templates:
Sample Outlook Mail App (C#)

2 Comments

Rustie says:

May 7, 2013 at 5:07 am

Hey,

I’m looking to fire off a function when pressing ‘Send’ on a new E-mail. Do you know if it’s possible to hook into this event?

Thanks.
Ty Anderson says:

May 7, 2013 at 10:49 pm

Hi Rustie,

I don’t think it is possible. The API for Office Apps is extremely limited.

The mail apps are intended to allow a developer to recognize a type of content (e.g. an address, phone number, or email address…) in a mail item and display additional information.

I recommend reviewing this page:
https://msdn.microsoft.com/en-us/library/fp161135.aspx

What you see is what you get. If you don’t find what your looking for there, it isn’t possible.