Posted by on Jan 20, 2016 in #Office365Dev | 4 comments

With the new application model for the Office applications comes the possibility to build Outlook add-ins. For you as developers, this means that you have a chance to integrate your solutions and ideas with one of the most used productivity suite in the world. Now bring Office Store into the mix… talk about a potential user base (customers)!

Building Outlook add-ins can be viewed as your way of getting showtime in the different surface areas of Outlook. As of right now, you can integrate with both messages (mail) and appointments (calendar). By nature, these item types are very similar – making it trivial when developing solutions for both of them.

In addition to integrating with the Outlook mail and calendar, you can choose to light up your solution in either read or compose mode of the target item type. Perhaps your solution only makes sense to light up in a specific scenario (i.e. when a user is writing a mail, or viewing a calendar event)?

These are different scopes that you can choose to align your solution for, so before getting started – consider which scenarios your solution makes sense within.

Creating Outlook add-ins with the new application model for Office is just like building a web app. Use your favorite tools and stacks to realize your ideas. In the end, what defines an Office add-in is a manifest file and the Office.js library ( The manifest file defines where in the world you are hosting your solution and what your target scope is (where in Outlook do you want to light up?). The Office.js library is your way of communicating with the Office context. In this blog post, I will cover some of the key possibilities that you have when integrating with Outlook and using the Office.js library.

Visual Studio Template

If you are using Visual Studio 2015 like me, you might need to go and grab the latest Office Development Tools at:

You are by no means restricted to using Visual Studio when building Outlook add-ins. Please note that the points I will be making in this blog post will apply regardless of your toolset.

Kick things off in Visual Studio by creating a new project, pick “Office add-in” as the starting template. You’ll find it in the “Office/SharePoint” tab.


Before Visual Studio is going to set up your Office add-in project, you will need to walk through a short wizard. This is where you will define the target scope of your Office add-in.

As for the Office add-in type, choose “Mail” to create an add-in for Outlook.


The last step is to configure which surface area of Outlook to integrate with. As mentioned you can integrate with messages (mail) and appointments (calendar) – in both read and/or compose mode.


By completing the wizard, Visual Studio will configure the manifest file for you. This manifest file will contain the above information for areas to integrate with – meaning that you can change these at any time if you so desire (by modifying the manifest file).

In addition, Visual Studio will configure a nice folder structure if you choose to integrate both with the read and compose mode (with separate files).


In addition to the folder structure, take a moment to examine the Home.js files. As messages and appointments in Outlook are very similar – the API set is also very much alike. However you’ll notice some distinction between the two item types in the Home.js files.


Javascript API

So exactly what can you do? Using the Office.js library you have a lot of access and interaction possibilities with the Outlook item. Your gateway is the Office.context.mailbox.item object.

If you examine the Home.js files you might notice a pattern here. Make sure to not use the Office.js library before the Office.initialize function has been called. This way you’ll know that you are not trying to do something too early.

Read vs. Compose mode

Depending on the mode your add-in is running within (read or compose), the Javascript API might behave slightly different. The reason is that when your add-in is running in the read mode of an Outlook item – the item data is static and can be loaded before the Office.initialize function is called. With that, you can access the item properties synchronously and get the values.

In the compose mode, the data isn’t static and must be read and/or written to the Outlook item itself. This is done via REST calls under the hood for you asynchronously. This however means that you will rely on callback functions, rather than getting the values right away.

To clarify, to get the subject property in the read mode you would access the property like so:

In compose mode, you need to use the getAsync method and pass a callback function.

Item Body

You can get access a body object that lets you deal with the body of the Outlook item. The body can be in two formats, either plain text or HTML.

If you are working with the body object, be sure to request a sufficient mailbox requirement set version in your manifest – as some functions (getAsync, setAsync) require at least version 1.3.

The functions prependAsync and setSelectedDataAsync only require version 1.1.

Message Recipients

You can get or set the recipients of a message by accessing the to/CC/BCC properties of the item. Pay attention to which mode your add-in is running in (read or compose, see section above).

In read mode, a collection of recipients is returned. Be aware that this collection is limited to 100 recipients.

The BCC property works just like the above example – it is only available in the compose mode.

Appointment Attendees

You can get or set the recipients of an appointment by accessing the attendee properties (requiredAttendees/optionalAttendees) of the item. Pay attention to which mode your add-in is running in (read or compose, see section above).

In read mode, a collection of recipients is returned synchronously.

Item Sender (From/Organizer)

You can get the sender of the item by accessing either the from property (message) or the organizer property (appointment). These two properties require you to be in the read mode.

Normalized Subject

In the read mode, you can get a trimmed version of the subject – the normalized subject. Essentially it removes the “RE:” and “FW:” prefixes and gets you a clean version of the subject.


You can access and attach attachments to both messages and appointments using the same functions. However you can only get attachments in the read mode, so keep track of attachments you’re adding to an item in the compose mode.

When adding an attachment, you can add either a file or an existing Exchange item (such as a message or an appointment).

The addFileAttachmentAsync function will let you pass in a URL to a file which will be uploaded to the item. Use the addItemAttachmentAsync to pass the (Exchange) ID of the existing item to be added as an attachment.

Appointment Date and Time

You can get or set the date and time of an appointment by accessing the start/end properties of the item. Pay attention to which mode your add-in is running in (read or compose, see section above).

These properties contains Coordinated Universal Time (UTC) date and time values. Use the Office.context.mailbox.convertToLocalClientTime function to convert the value to a local date and time. Remember to use UTC values when setting the date and time, use the Office.context.mailbox.convertToUtcClientTime function if needed.

Appointment Location

You can get or set the location of an appointment by accessing the location property of the item. Pay attention to which mode your add-in is running in (read or compose, see section above).

The location is a string value much like the subject property.

Custom Properties

You can persist custom properties on messages and appointments by using the custom properties object. These are stored on the item itself. Remember to call the saveAsync function on the object to reflect the changes back to the server.

Read more about using custom properties at:

Entities and RegEx matches

Provided on the item object is a few functions that lets you search the message or appointment (subject and body) for entities or RegEx matches. These entities are any known types by Outlook, such as contacts, meeting suggestions, phone numbers, etc.

As for RegEx matches, these are defined in your manifest file and identified by unique names. These functions require you to be in the read mode.

Save and Close

You can save the current item as a draft and return the item ID via a callback using the saveAsync function on the item. Additionally you can request to close an item with the close function (the close function will behave differently depending on if there are unsaved changes or not).

Both of these functions are exposed in the compose mode and requires a minimum mailbox requirement set version of 1.3.

Wrap up

These are a few key points when it comes to functionality and integrating with the Outlook surface areas and features. You can learn about the API set and find more details at:

Also, you can learn more about developing Outlook add-ins at:

This should give you an overview of the API set and its functionalities. You more or less have access and interaction abilities with the entire Outlook items – so the possibilities are many!

With Outlook add-ins, you have a chance of getting into the flow where millions of users are spending hours and hours each and every day. It’s your chance to build something valuable, something that helps users get things done – faster and better!

-Simon Jaeger