Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All

Save item-specific metadata as custom properties

Office Add-ins

Learn about custom properties that allow you to store data about the message or appointment that the user is viewing or composing in Outlook.

Last modified: May 01, 2015

Applies to: apps for Office | Office Add-ins | Outlook

Learn more about supported hosts and other requirements.

Note Note

The name "apps for Office" is changing to "Office Add-ins". During the transition, the documentation and the UI of some Office host applications and Visual Studio tools might still use the term "apps for Office". For details, see New name for apps for Office and SharePoint.

In this article
Custom properties and MAPI-based properties
Using custom properties
Custom properties example
Additional resources

The apps for Office platform lets you create a property bag to store data as strings for the item that the user is viewing or composing in Outlook. This property bag is accessible by only the mail app that created it, is stored for that item on the Exchange server, and can be retrieved when the item is reopened on any device supported by that app.

For example, if your mail app creates appointments from meeting suggestions in a message, you can use a custom property to track each of these appointments. This ensures that if the user opens the message again, your mail app does not offer to create the appointment a second time.

These app-specific, item-specific custom properties are represented in the JavaScript API for Office as CustomProperties, and can be accessed by using only the CustomProperties object. These properties are different from the custom, MAPI-based, UserProperties in the Outlook object model, and extended properties in Exchange Web Services (EWS). You cannot access CustomProperties by using the Outlook object model or EWS.

On the other hand, a mail app can get MAPI-based extended properties by using the EWS GetItem operation. Access GetItem on the server side by using a callback token, or on the client side by using the Mailbox.makeEwsRequestAsync method. In the GetItem request, specify the custom extended properties you need in a property set. A mail app can also use makeEwsRequestAsync and EWS CreateItem and UpdateItem operations to create and modify extended properties.

For more information about MAPI properties, Outlook UserProperties, EWS extended properties, using the callback token mechanism and makeEwsRequestAsync, see the Additional resources section.

Before you can use custom properties, you must load the property bag by calling the loadCustomPropertiesAsync method. If any custom properties are already set for the current item, they are loaded from the Exchanger server at this point. After you have created the property bag, you can use the set and get methods to add and retrieve custom properties. To save any changes that you make to the property bag, you must use the saveAsync method to persist the changes on the Exchange server.

Note Note

Because Outlook for Mac doesn’t cache custom properties, if the user’s network goes down, mail apps in Outlook for Mac would not be able to access their custom properties.

The following table lists the objects and methods that you use with custom properties.

Object name

Method name and parameters


Item (Appointment, Message, MeetingRequest)

loadCustomPropertiesAsync(callback, userContext)

Creates a property bag of custom properties and provides methods for working with the property bag. When the asynchronous call finishes, the method specified in the callback parameter is called by using one parameter, asyncResult, which contains the property bag in its value property. You can use the optional userContext parameter to pass state to the callback function.


set(name, value)

Sets a property to a value. If the property does not exist, the property is created. If the property does exist, the existing value is replaced with the new value.



Gets a property value. The value can be of any type, but it is always returned in its string representation.



Removes the custom property from the property bag.


saveAsync(callback, userContext)

Saves the custom property bag on the Exchange server. Changes made with the set and remove methods are not persisted unless this method is called. When the asynchronous call finishes, the method specified in the callback parameter is called.

The following example shows a simplified set of methods for a mail app that uses custom properties. You can use this example as a starting point for your mail app that uses custom properties.

A mail app that uses this code retrieves any custom properties by calling the get method on the _customProps variable, as shown in the following example.

var property = _customProps.get("propertyName");

This example includes the following methods:

  • Office.initialize — Initializes the app and loads the custom property bag from the Exchange server.

  • customPropsCallback — Gets the custom property bag that is returned from the Exchange server and saves it for later use.

  • updateProperty — Sets or updates a specific property, and then saves the change to the Exchange server.

  • removeProperty — Removes a specific property from the property bag, and then saves the removal to the Exchange server.

/// <reference path="Scripts/Office.js" />
/// <reference path="Scripts/Outlook-15.js" />
/// <reference path="Scripts/MicrosoftAjax.js" />

var _mailbox;
var _customProps;

// The initialize function is required for all apps.
Office.initialize = function () {
    _mailbox = Office.context.mailbox;

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

function customPropsCallback(asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        // Handle the failure.
    else {
        _customProps = asyncResult.value;

function updateProperty(name, value) {
    _customProps.set(name, value);

function removeProperty(name) {

function saveCallback() {
© 2015 Microsoft