Apps for Office: Mail Apps Part 1 - Setup and Activation

So far we have reviewed building task pane and content apps, which extend functionality for Microsoft office applications like Word, Excel and PowerPoint. Mail apps, on the other hand, are an entirely different class of apps, designed to work specifically with Outlook.

In this first of two posts on Mail Apps, we’ll look at how to create a new project as well as the different options for launching and activating the map in different scenarios.

Create the project

Mail apps are built like any other App for Office, using the visual studio template to select the appropriate type.

However, mail apps differ from the other two options in that they can operate in two modes: read and compose. Each mode can then be targeted to a specific Outlook item, either Message or Appointment, as shown in the options dialog when creating a project.

Depending on the needs of your app, you can mix and match these options to suit. For this example we’ll simply enable all of the options, and see in our next post what API methods are available for each.

Launch Options

By default, Mail apps are configured to launch Outlook online, and prompt you for the appropriate credentials to test. Enter your mailbox credentials, which can also be saved for later reuse.

This option can be changed so that instead it launches the standard desktop Outlook client by opening the properties of the Office project and selecting the launch option shown. We’ll be using this option going forward for the sample app.

If we run the sample project generated by visual studio, you’ll see the app appear upon selection of any message or appointment in the inbox.

Since we also enabled Compose for the app, it will be available when we create a new item as well. However, before we can show it, the app must be installed into the item. This is done similarly to installing apps on other office clients from the ribbon menu.

Visual Studio automatically registered your app for use and testing within the outlook client — and because we enabled compose — it will also allow the app to be installed.

Also, since Apps for Office are designed for availability and portability, they will even run in the web version of Outlook:

Activation Rules

Because we specified both Read and Compose when creating the project, it is available for activation in both modes. What actually happens behind the scenes is that the app manifest file is updated with activation rules.

Rules and Rule Collections

When we selected the options for Read and Compose, we were actually creating a Rule which serves as a trigger, informing Outlook to enable the app for use. Selecting the default options as we did for this project is the simplest rule definition, which enables the app for any and every appropriate item.

Rules can be much more granular however, allowing you to only expose the app when it makes sense for the user. For example, the Bing maps app from Microsoft only reveals itself when an address is detected within the read-only view of a message or appointment.

As mentioned, Rules are defined within the app manifest file and can be seen by opening the xml view of the manifest in the Solution Explorer:

An app can be constrained by a single rule (such as whether or not an item is an email message), or it can be constrained by a grouped rule collection, which enables you to use logical operations on a set of rules to define activation. These collections can be nested to create complex activation rules.

Notice that the both definitions are of the abstract element type Rule and must therefore include an additional type property which specifies what type of rule is being applied. A collection is made up of several single Rules, and has an additional Mode property to specify the logic operation (AND vs OR) for processing the list of rules.

You can get as granular as your app requires via the XML editor. However, there is also a friendlier UI that can be used by opening the manifest editor instead by double clicking it from the Solution Explorer.

This editor allows you to easily define and modify rules for both the read and compose modes, as well as switch the logical operators for the rule collection.

You can also add additional rules from the drop down menu, revealing several useful and time saving selections.

Rule Types and Known Entities

A rule can be of several different types that constrain activation on different criteria. For example, a Rule can be set to only enable the app if it is an email message in read-view only. This Rule would be of the type ItemIs which accepts different Outlook item types, as well as the ItemFormType to specify the mode (Read vs Compose) of the item.

Other Rule types are available for different simple scenarios, such as ItemHasAttachment and ItemHasRegularExpressionMatch to detect attachments and custom string patterns. One very useful type, ItemHasKnownEntity, has a pre-defined KnownEntityType enumeration, which exposes several helpful options for detecting familiar content such as Addresses, Urls, Email Addresses, and Phone Numbers.

The ItemHasKnownEntity lets you quickly respond to the most common content situations without having to create complex regular expressions or rule collections. We’ll make use of these in the next post on this topic.

If you need to detect content that is not a “Known Entity”, you can use the regular expression activation rule to create custom Rules.

Rule Limitations

Before wrapping up, it’s important to mention that there are some limitations to the Rule definitions in the App Manifest. For example, the App Manifest file (which contains the XML definitions) cannot be larger than 32KB. If the file exceeds this maximum, the app itself will not install.

As of this writing, you are also limited to a maximum of 15 activation rules, of which a maximum of 5 can be regular expressions.

These rules are likely to change as new versions of the Office API are released, so for the latest updates, be sure to check out the MSDN documentation, which also specifies additional limitations on the JavaScript API for Mail Apps: Limits for activation and JavaScript API for Mail apps in Outlook

Wrapping Up and Next Steps

Mail apps have a variety of options for defining when they should be enabled within an Outlook item, whether by the item Type, the Mode, or a specific set of criteria within the content of the item. Leveraging different combinations allows you to target specific messages or appointments, showing your app only when it makes the most sense for your users.

Now that we have an understanding of how a Mail App can be activated, we can take a look at some of the API methods we can utilize to create a sample app, which will be the topic of our next post.