How to: Persist metadata for the same Outlook item in a mailbox using custom properties

apps for Office

See sample code that stores data specific to an Outlook item in the user’s mailbox on, and accesses the data subsequently on the supported Outlook hosts and form factors.

Last modified: February 27, 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
Loading and getting custom properties
Creating or setting a custom property
Removing a custom property
Additional resources

In Outlook, a mail app can use the CustomProperties object to save data that is specific to an item in the user’s mailbox. This data is accessible in subsequent Outlook sessions by only that app. The data is stored on the Exchange Server for that mailbox, and is accessible in subsequent Outlook sessions on all the form factors that the app supports.

A mail app typically loads custom properties of the current item in the Office.initialize event handler. The following JavaScript code example shows how to load and get custom properties. The example calls the Item.loadCustomPropertiesAsync method to load custom properties of the current item, and passes the callback method myLoadAllCustomPropertiesCallback. Outlook calls the callback method after loading all the custom properties for the item. The myLoadAllCustomPropertiesCallback method gets a custom property. You can further customize the callback method to use the custom properties for the current item.

//Global variables for sample code in this topic.
var _mailbox;
var _Item;
var _CustomProps;

// The initialize function is required for all apps.
Office.initialize = function (reason) {
    // Initialize instance variables to access API objects.
    _mailbox = Office.context.mailbox;
    _Item = _mailbox.item;

    // Checks for the DOM to load using the jQuery ready function.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.

function onInitializeComplete()
    // Load custom properties for the current item.

// Obtains existing custom properties for the current item.
// The custom properties are passed in an object parameter to this callback method.
// Uses the CustomProperties.get method to get the value of the 
// "custom_property_name" property by name.

function myLoadAllCustomPropertiesCallback(obj)
     if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        // Handle the failure.
    else {
        _CustomProps = obj.value;

        if (_CustomProps.get("custom_property_name")) {
            var propValue = _CustomProps.get("custom_property_name");
            // Do something with propValue.

        // Do something with other custom properties in _CustomProps.

Continuing with the preceding example, the following JavaScript function, setCustomProperty, shows how to use the CustomProperties.set method to set a custom property named custom_property_name with the value value, and persist the data by using the CustomProperties.saveAsync method to save all the custom properties for the item back to the Exchange Server. The set method creates the property if the property does not already exist, and assigns the property to the specified value. The saveAsync method saves properties asynchronously. This code sample passes a callback method, saveMyCustomPropertiesCallback, to saveAsync. When the asynchronous call finishes, saveMyCustomPropertiesCallback is called by using one parameter, asyncResult. This parameter is an AsyncResult object that contains the result of and any details about the asynchronous call. You can use the optional userContext parameter to pass any state information from the asynchronous call to the callback function.

// Sets a custom property on an item and persists its value by 
// using saveAsync and passing a callback method saveMyCustomPropertiesCallback.
// Property name is "custom_property_name", property value is "value".
function setCustomProperty()
    _CustomProps.set("custom_property_name", "value");

// Callback method after saving custom properties.
function saveMyCustomPropertiesCallback(asyncResult)
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        // Handle the failure.
    // Do something here.

Also extending the preceding examples, the following JavaScript function, removeCustomProperty, shows how to use the CustomProperties.remove method to remove the custom_property_name property and save all the custom properties for the current item back to the Exchange Server.

// Removes a custom property from an item.
// Removes the custom property named custom_property_name and then save.
function removeCustomProperty()
© 2014 Microsoft