CustomProperties object (JavaScript API for Office)

Office Add-ins

Provides a collection of item-specific custom properties.

Last modified: July 06, 2015

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.


App type: Mail

Available in requirement sets


Last changed in Mailbox


Applicable Outlook modes

Compose or read

See all support details



Method name

Outlook mode


Introduced in


Compose or read

Gets the specified custom property.

Version 1.0


Compose or read

Removes the specified custom property.

Version 1.0


Compose or read

Saves the custom property collection to the server.

Version 1.0


Compose or read

Creates or updates the specified custom property.

Version 1.0

The CustomProperties object represents custom properties that are specific to a particular item and specific to a mail app for Outlook. For example, there might be a need for a mail app to save some data that is specific to the current email message that activated the app. If the user revisits the same message in the future and activates the mail app again, the app will be able to retrieve the data that had been saved as custom properties.

Because Outlook for Mac doesn’t cache custom properties, if the user’s network goes down, mail apps cannot access their custom properties.

In this article, "Outlook" refers to Outlook for Windows, Outlook for Mac, Outlook RT, OWA for Devices (OWA for Android phones, OWA for iPad, OWA for iPhone), and Outlook Web App. "Outlook rich clients" refers to Outlook for Windows, Outlook for Mac and Outlook RT. At this point, Outlook for Mac supports JavaScript API for Office in only Outlook read mode, and can activate mail apps that reference office.js version 1.0 or 1.1 and use apps for Office schema version 1.0.

The following example shows how to use the Item.loadCustomPropertiesAsync method to asynchronously load custom properties that are specific to the current item in Microsoft Outlook. The example also shows how to use the CustomProperties.saveAsync method to save these properties back to the Exchange server. After loading the custom properties, the example uses the CustomProperties.get method to read the custom property myProp, the CustomProperties.set method to write the custom property otherProp, and then finally calls the saveAsync method to save the custom properties.

// The initialize function is required for all apps.
Office.initialize = function () {
    // Checks for the DOM to load using the jQuery ready function.
    $(document).ready(function () {
    // After the DOM is loaded, app-specific code can run.
    var mailbox = Office.context.mailbox;
function customPropsCallback(asyncResult) {
    var customProps = asyncResult.value;
    var myProp = customProps.get("myProp");

    customProps.set("otherProp", "value");

function saveCallback(asyncResult) {

A checkmark (√) in the following table indicates that this property is supported in the corresponding Outlook host application. An empty cell indicates that the Outlook host application doesn't support this property.

For more information about Office host application and server requirements, see Requirements for running apps for Office.

Supported hosts, by platform

Office for Windows desktop

Office Online
(in browser)

OWA for Devices

Office for Mac


√ (Read mode only)

Available in requirement sets


Minimum permission level


App types










© 2015 Microsoft