Start with fundamental concepts for mail apps in Outlook

apps for Office

Explore the major features available to developing mail apps for Outlook, and see sample JavaScript and XML code snippets of how to access these features.

Last modified: June 09, 2014

Applies to: Exchange Online | Exchange Server 2013 | Exchange Server 2013 SP1 | Outlook 2013 | Outlook 2013 RT | Outlook 2013 SP1 | Outlook Web App | OWA for Devices

   Office.js: v1.0, v1.1

   Apps for Office manifests schema: v1.0, v1.1

Note Note

"Outlook" in this article refers to the Outlook rich client, Outlook RT, Outlook Web App, and OWA for Devices.

In this article
JavaScript API available to mail apps
Object model maps
Contextual activation
Matches of known entities or regular expressions
Outlook roaming settings
Item custom properties
Item properties
Attachments
Entire selected item including item body
User profile
Authentication
Permissions model and governance
Exchange Web Services
In this section
Additional resources

This section gives an overview of the subset of the JavaScript API for Office (v1.1) that is specific to mail apps, based on the most recent release, v1.1, of the JavaScript API for Office. Figure 1 shows the objects and enumerations that mail apps can access in a compose form using v1.1 of the API. Figure 2 shows the objects and enumerations that are accessible in a read form, also using v1.1 of the API.

Figure 1. Objects and enumerations in v1.1 of JavaScript API for Office that are available to mail apps in a compose form

Object model for mail apps compose mode
Figure 2. Objects and enumerations in v1.1 of JavaScript API for Office that are available to mail apps in a read form

Object model for mail apps read mode

Conceptually, you can view and categorize these objects in the following ways:

  1. Common objects shared with other apps for Office

    These objects include Office, Context and AsyncResult. The Office object is the root object of the JavaScript API for Office. The Context object represents the runtime environment. Both Office and Context are the fundamental objects for any app for Office. The AsyncResult object represents the results of an asynchronous operation, for example, when a mail app saves or loads item-level custom properties or saves mail app settings.

  2. The Mailbox object

    The majority of the subset of the API available to mail apps is exposed through the Mailbox object. Using this subset of API, a mail app can access the features described in the later part of this topic.

    A mail app can access the Office.context.mailbox property to get the Mailbox object, and through the Mailbox object, can access most of the API belonging to the subset, such as the UserProfile and Item objects. The mail app can get the Mailbox object only after the run-time environment has been loaded, typically in the event handler for the Office.initialize event. The following is an example of a handler for the Office.initialize event, where the mail app gets the currently selected item from the item property of the Mailbox object.

    // The initialize function is required for all apps.
    Office.initialize = function () {
        item = Office.context.mailbox.item;
        // Check for the DOM to load using the jQuery ready function.
        $(document).ready(function () {
        // After the DOM is loaded,
        // continue any processing using the item object.
        });
    }
    
    
  3. Mail app-specific data

    Mail apps can store and load custom data at two levels:

    • At an item level, the CustomProperties object allows a mail app to save and load data for a specific item in the user’s mailbox. You can get the CustomProperties object through the AsyncResult.value property, when the call to the Item.loadCustomPropertiesAsync method completes.

    • At a mailbox level, the RoamingSettings object allows a mail app to persist data for a specific user mailbox, over any form factor (desktop, tablet, smartphone) supported by the mail app. You can get the RoamingSettings object by accessing the Office.context.roamingSettings property.

  4. Supported item objects

    The supported item objects include Appointment and Message each of which inherits from Item, and the MeetingRequest object that inherits from Message. These objects represent the types of Outlook items that support mail apps: calendar items of appointments and meetings, and message items such as email messages, meeting requests, responses, and cancellations.

  5. Data accessible on an item

    Data on an item can be accessed by properties exposed on that type of item (such as the Appointment.subject and Message.attachments properties), as well as objects and members that support certain well-known Entities objects that may exist on the subject or body of the item (for example, Contact, MeetingSuggestion, PhoneNumber, and TaskSuggestion entities, and Message.getEntitiesByType method).

    Note Note

    Starting in v1.1 of the apps for Office platform, Outlook can activate mail apps when the user is composing an item, in addition to the read scenario that been supported since v1.0. The specific data accessible on an item depends on whether the mail app is activated in a compose form or read form. See Item properties for more details.

    See figure 1 for the objects that mail apps can access in a compose form, using v1.1 of the JavaScript API for Office. See figure 2 for those accessible in a read form, also using v1.1 of the API.

For a more complete view, explore all the objects and members in v1.1 that are applicable to mail apps by using ZoomIt, or by downloading the comprehensive set of maps and scrolling to the mail app-specific map.

Objects and members for mail apps in both modes

Zoom v1.1 map

Download v1.1 maps

If you are creating a new mail app, you should use at least v1.1 of the API. If you are working with an existing mail app that uses v1.0, you can see the maps here:

Zoom v1.0 map

Or download the comprehensive set of maps for v1.0, and scroll to the mail app-specific map:

Download v1.0 maps

Read more about the considerations for choosing a version of the platform for your new mail app.

The following sections highlight the fundamental concepts for creating mail apps for Outlook. For more details about a concept, see the references at the end of the concept, and also the Additional resources section.

Mail app activation in Outlook is contextual based on the item that the user is currently composing inline in the Outlook explorer or compose inspector, or reading in the Reading Pane or read inspector. You can have Outlook activate a mail app all the time for any item in the mailbox, or you can define rules that cause Outlook to activate a mail app for an item only if certain conditions are met. Activation rules are based on one or more of the following criteria:

  • Item type—Activates a mail app for a specific type of item (an email message, meeting request message, or appointment), when the user is composing or reading the item.

  • Item message class—Activates a mail app if the item that the user is reading is of a specific built-in or custom item type. For example, a social networking add-in can send email messages that have a custom message class, IPM.Note.Contoso, and an app can activate on an email message that has this custom message class. You can use custom message classes that inherit from only IPM.Note or IPM.Appointment.

  • Existence of certain entities or string matches of these entities—Activates a mail app if certain entities exist in the subject or body of the item that’s being read by the user. Examples of recognized entities include phone number, email address, and postal address. You can define regular expressions to further require string matching in these entities (for example, an item with a body that contains a phone number).

  • String matches in certain properties of the item—Activates a mail app if certain string patterns exist in certain properties of the item that’s being read by the user. You can define one or more regular expressions for the subject, body, and the sender’s SMTP address of the item.

You can organize multiple activation rules in a collection and apply logical AND or OR operators accordingly. The following rule collection includes a regular expression and activates the corresponding mail app when the user is reading an email or meeting request message that contains a telephone number in the body.

<Rule xsi:type="RuleCollection" Mode="And">
    <Rule xsi:type="ItemIs" FormType="Read" ItemType="Message"/> 
    <Rule xsi:type="ItemHasRegularExpressionMatch" RegExName="reg1" RegExValue="((\(\d{3}\) ?)|(\d{3}-))?\d{3}-\d{4}" PropertyName="BodyAsPlaintext"/>
</Rule>

See the following topics for more details and sample code:

A mail app that is activated in the read form of an item can access any matching results for well-known entities. If that mail app specifies regular expressions in its activation rules, it can also access any matches for the regular expressions for further processing. For example, an app for Voice Over IP dialing can activate when there are telephone numbers in the message body, and display each match as a hyperlink to dial that telephone number. Behind the scenes, the mail app can choose to activate in more than one way:

  • Based on the existence of the telephone number entity:

    <Rule xsi:type="ItemHasKnownEntity" 
      EntityType="PhoneNumber"/>
    
  • Based on a regular expression match of a telephone number:

    <Rule xsi:type="ItemHasRegularExpressionMatch" 
        RegExName="teleMatch" 
        RegExValue="((\(\d{3}\) ?)|(\d{3}-))?\d{3}-\d{4}" 
        PropertyName="BodyAsPlaintext"
    />
    
    

    The mail app can then obtain the matches for the regular expression, teleMatch, defined in the app manifest, as shown below:

    Office.initialize = function () {
        var matches = Office.mailbox.item.getRegExMatches().teleMatch;
        // Proceed to process the returned array of string matches.
    }
    

Regardless of the type of activation rule used, the mail app can obtain matches for a telephone number as shown below:

Office.initialize = function () {
    var item = Office.mailbox.item;
    var addresses = item.getEntitiesByType(Office.MailboxEnums.EntityType.PhoneNumber);
    // Proceed to process the returned string array of phone numbers.
}

In general, depending on the kind of entities you are looking for, you can get an array of objects representing entities by using the getEntities, getEntitiesByType, or getFilteredEntitiesByName method of the item.

See the following topics for more details and sample code:

A mail app can save data that is specific to the user’s mailbox on the Exchange server for access in a subsequent Outlook session. Only that app can access these roaming settings. If the app is designed to run on multiple Outlook clients and form factors, the settings roam with the supported Outlook client and form factor. Roaming settings are specific to the user’s mailbox as a whole, are not specific to a particular item, and are available regardless of whether the app is activated in a compose or read form of an item in the mailbox. The following example shows how to obtain Outlook settings in the initialize event handler of the app.


var _settings;

Office.initialize = function () {
    // Initialize instance variables to access API objects.
    mailbox = Office.context.mailbox;
    settings = Office.context.roamingSettings;
}

For more sample code, see How to: Persist metadata for the same mailbox by using roaming settings.

A mail app can save data that is specific to an item in the user’s mailbox on the Exchange server for access in a subsequent Outlook session. Only that app can access these custom properties. If the app is designed to run on multiple Outlook clients and form factors, the custom properties roam with the supported Outlook client and form factor. Custom properties are available regardless of whether the app is activated in a compose or read form of the item. The following example shows how to load, get, set, and save custom properties for the current item.

Office.initialize = function () {
    var mailbox = Office.context.mailbox;
    // Check for the DOM to load using the jQuery ready function.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        mailbox.item.loadCustomPropertiesAsync(customPropsCallback);
    });
}

function customPropsCallback(asyncResult) {

    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        // Handle the failure.
    }
    else {
        // Do something here.
        var customProps = asyncResult.value;
        var myProp = customProps.get("myProp");
        customProps.set("otherProp", "value");
        customProps.saveAsync(savePropsCallback);
    }
}

function savePropsCallback(asyncResult) {
}

For more details and sample code, see the following topics:

A mail app can access built-in properties of the item that the user is composing or reading, for example, the sender, recipients, and subject of a message, and the location, start time, end time, and attendees of a meeting request or appointment. Starting in v1.1 of the apps for Office platform, Outlook can activate mail apps in a compose form, in addition to read forms as supported in v1.0. The specific properties and methods accessible on the item depend on whether the user is in the compose or read form of the item, since some properties are only meaningful in one type of form but not the other. For example, the bcc property of a message which can be set in a compose form but cannot be viewed or read in a read form. Other properties that are available in both compose and read forms are accessed as different types and by different means in each type of form. For example, the subject of a message is a Subject object in a compose scenario, accessible asynchronously by the getAsync and setAsync methods to accommodate possibly simultaneous access of the property by the user and the mail app. In a read scenario, the subject is simply a string accessible synchronously from the parent item object, as shown in the following example:

Office.initialize = function () {
    var item = Office.context.mailbox.item;
    var subject = item.subject;
}

For more details, see the following:

A mail app can access attachments in different ways depending on whether the mail app is activated when the user is composing or reading an item. Activated in a compose form, a mail app can add and remove attachments from an item, by using the addFileAttachmentAsync, addItemAttachmentAsync, or removeAttachmentAsync method of the item. For details, see Add and remove attachments to an item in a compose form in Outlook.

Activated in a read form, a mail app can send its server-side code (such as a web service) a callback token and attachment identifier to enable the web service to retrieve the attachment from the Exchange server. The following are the supporting methods and properties:

  • Mailbox.getCallbackTokenAsync method – allows an asynchronous call to the user’s Exchange Server to get a callback token to subsequently identify server-side code of the app.

  • attachments property of the appointment or message item being read by the user – provides an array of AttachmentDetails objects which include metadata such as attachment IDs of all the attachments of the item.

  • Mailbox.ewsUrl property – provides the URL end point of Exchange Web Services (EWS) on the Exchange Server that hosts the user’s mailbox. A mail app can pass this URL, the callback token for the Exchange Server, and attachment IDs for specific attachments of the item to server-side code. The server-side code can then access the GetAttachment EWS operation and get the actual attachments.

For more details and sample code, see the following topics:

Similar to using a callback token to get attachments of the item that the user is reading, a mail app can get the entire selected item including the item body. The mail app can send its server-side code a callback token, item ID, and an EWS endpoint URL for the user’s mailbox to enable getting the entire selected item from the Exchange server. The following are the supporting methods and properties:

  • Mailbox.getCallbackTokenAsync method – provides a callback token to identify the app’s server side code for the Exchange Server.

  • Item.itemId property – identifies the item that the user is reading and that the server-side code is getting.

  • Mailbox.ewsUrl property – provides the EWS endpoint URL which, together with the callback token and item ID, the server-side code can use to access the GetItem EWS operation to get the entire item.

A mail app can access the display name, email address, and time zone in the user’s profile. The UserProfile object is available regardless of whether the app is activated in a compose or read form of the item. The following example shows how to obtain the user’s display name from the profile.

Office.initialize = function () {
    var userProfile = Office.context.mailbox.userProfile;
    var name = userProfile.displayName;
}

A mail app can authenticate a user by using a token that identifies the user’s email account on an Exchange Server. The token includes a header, payload, and signature. User identity tokens are available regardless of whether the app is activated in a compose or read form of the item. The following example shows the basic technique to obtain an identity token for the current user from the Exchange Server, and passes the token to the web service that requires the user authentication. The mail app requests a token from the Exchange Server and provides a callback method. The callback method is called when the asynchronous request to the Exchange Server returns. The callback method gets the token from its input parameter and creates the web service call.

var _mailbox;
var _xhr;

Office.initialize = function () {
    _mailbox = Office.context.mailbox;

    // Request identity token from Exchange Server.
    _mailbox.getUserIdentityTokenAsync(getTokenCallback);
}

function getTokenCallback(asyncResult) {
    var token = asyncResult.value;

    // Create a web service call and pass the token as part of the call.
    _xhr = new XMLHttpRequest();
    _xhr.open("POST", "https://localhost:44300/IdentityTestService/UnpackTokenJSON");
    _xhr.setRequestHeader("Content-Type", "application/json; charset=utf-8");
    _xhr.onreadystatechange = readyStateChange;

    var request = new Object();
    request.token = token;
    request.phoneNumbers = _om.get_item().getEntities().phoneNumbers;

    _xhr.send(JSON.stringify(request));
}


For more information about using identity tokens and web service response and, see Authenticate a mail app by using Exchange identity tokens.

Outlook supports a four-tier permissions model that provides the basis for privacy and security for end users of mail apps. App developers request the permission level that is appropriate for their needs, and follow implementation and resource usage guidelines. IT administrators can use group policy settings to control performance-related thresholds.

For more details, see the following topics:

Given the appropriate ReadWriteMailbox permissions, a mail app can perform some tasks through Exchange Web Services (EWS), regardless of whether the app is activated in a compose or read form of the item. The EWS operations include the following:

  • Looking up mail messages, meeting request messages, and appointments.

  • Creating mail messages, meeting request messages, appointments, and tasks.

  • Sending messages and meeting requests.

For a list of EWS available to mail apps, see the section Read/write mailbox permission. For more details, see Call web services from a mail app for Outlook.

Show:
© 2014 Microsoft