Office.Categories interface

Represents the categories on an item.

In Outlook, a user can group messages and appointments by using a category to color-code them. The user defines categories in a master list on their mailbox. They can then apply one or more categories to an item.

Important: In Outlook on the web, you can't use the API to manage categories on a message in Read mode.

[ API set: Mailbox 1.8 ]

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Compose or Read

Methods

addAsync(categories, options, callback)

Adds categories to an item. Each category must be in the categories master list on that mailbox and so must have a unique name but multiple categories can use the same color.

addAsync(categories, callback)

Adds categories to an item. Each category must be in the categories master list on that mailbox and so must have a unique name but multiple categories can use the same color.

getAsync(options, callback)

Gets an item's categories.

getAsync(callback)

Gets an item's categories.

removeAsync(categories, options, callback)

Removes categories from an item.

removeAsync(categories, callback)

Removes categories from an item.

Method Details

addAsync(categories, options, callback)

Adds categories to an item. Each category must be in the categories master list on that mailbox and so must have a unique name but multiple categories can use the same color.

addAsync(categories: string[], options?: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

categories
string[]

The categories to be added to the item.

options
Office.AsyncContextOptions

Optional. An object literal that contains one or more of the following properties. asyncContext: Developers can provide any object they wish to access in the callback method.

callback
(asyncResult: Office.AsyncResult<void>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult.

[Api set: Mailbox 1.8]

Returns

void

Remarks

Minimum permission level: ReadWriteItem

Applicable Outlook mode: Compose or Read

Errors:

  • InvalidCategory: Invalid categories were provided.

addAsync(categories, callback)

Adds categories to an item. Each category must be in the categories master list on that mailbox and so must have a unique name but multiple categories can use the same color.

addAsync(categories: string[], callback: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

categories
string[]

The categories to be added to the item.

callback
(asyncResult: Office.AsyncResult<void>) => void

When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. If adding categories fails, the asyncResult.error property will contain an error code.

[Api set: Mailbox 1.8]

Returns

void

Remarks

Minimum permission level: ReadWriteItem

Applicable Outlook mode: Compose or Read

Errors:

  • InvalidCategory: Invalid categories were provided.

Examples

// Note: In order for you to successfully add a category,
// it must be in the mailbox categories master list.

var categoriesToAdd = ["Urgent!"];

Office.context.mailbox.item.categories.addAsync(categoriesToAdd, function (asyncResult) {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
        console.log("Successfully added categories");
    } else {
        console.log("categories.addAsync call failed with error: " + asyncResult.error.message);
    }
});

getAsync(options, callback)

Gets an item's categories.

getAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<CategoryDetails[]>) => void): void;

Parameters

options
Office.AsyncContextOptions

An object literal that contains one or more of the following properties. asyncContext: Developers can provide any object they wish to access in the callback method.

callback
(asyncResult: Office.AsyncResult<CategoryDetails>) => void[]

When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. If adding categories fails, the asyncResult.error property will contain an error code.

[Api set: Mailbox 1.8]

Returns

void

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Compose or Read

getAsync(callback)

Gets an item's categories.

getAsync(callback: (asyncResult: Office.AsyncResult<CategoryDetails[]>) => void): void;

Parameters

callback
(asyncResult: Office.AsyncResult<CategoryDetails>) => void[]

When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult.

[Api set: Mailbox 1.8]

Returns

void

Remarks

Minimum permission level: ReadItem

Applicable Outlook mode: Compose or Read

Examples

Office.context.mailbox.item.categories.getAsync(function (asyncResult) {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.log("Action failed with error: " + asyncResult.error.message);
    } else {
        var categories = asyncResult.value;
        console.log("Categories:");
        categories.forEach(function (item) {
            console.log("-- " + JSON.stringify(item));
        });
    }
});

removeAsync(categories, options, callback)

Removes categories from an item.

removeAsync(categories: string[], options?: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

categories
string[]

The categories to be removed from the item.

options
Office.AsyncContextOptions

Optional. An object literal that contains one or more of the following properties. asyncContext: Developers can provide any object they wish to access in the callback method.

callback
(asyncResult: Office.AsyncResult<void>) => void

Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. If removing categories fails, the asyncResult.error property will contain an error code.

[Api set: Mailbox 1.8]

Returns

void

Remarks

Minimum permission level: ReadWriteItem

Applicable Outlook mode: Compose or Read

removeAsync(categories, callback)

Removes categories from an item.

removeAsync(categories: string[], callback: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameters

categories
string[]

The categories to be removed from the item.

callback
(asyncResult: Office.AsyncResult<void>) => void

When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. If removing categories fails, the asyncResult.error property will contain an error code.

[Api set: Mailbox 1.8]

Returns

void

Remarks

Minimum permission level: ReadWriteItem

Applicable Outlook mode: Compose or Read

Examples

var categoriesToRemove = ["Urgent!"];

Office.context.mailbox.item.categories.removeAsync(categoriesToRemove, function (asyncResult) {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
        console.log("Successfully removed categories");
    } else {
        console.log("categories.removeAsync call failed with error: " + asyncResult.error.message);
    }
});