Office.MasterCategories interface

Represents the categories master list on the mailbox.

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.

[ API set: Mailbox 1.8 ]

Remarks

Minimum permission level: ReadWriteMailbox

Applicable Outlook mode: Compose or Read

Methods

addAsync(categories, options, callback)

Adds categories to the master list on a mailbox. Each category must have a unique name but multiple categories can use the same color.

addAsync(categories, callback)

Adds categories to the master list on a mailbox. Each category must have a unique name but multiple categories can use the same color.

getAsync(options, callback)

Gets the master list of categories on a mailbox.

getAsync(callback)

Gets the master list of categories on a mailbox.

removeAsync(categories, options, callback)

Removes categories from the master list on a mailbox.

removeAsync(categories, callback)

Removes categories from the master list on a mailbox.

Method Details

addAsync(categories, options, callback)

Adds categories to the master list on a mailbox. Each category must have a unique name but multiple categories can use the same color.

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

Parameters

categories
CategoryDetails[]

The categories to be added to the master list on the mailbox.

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: ReadWriteMailbox

Applicable Outlook mode: Compose or Read

Errors:

  • DuplicateCategory: One of the categories provided is already in the master category list.

  • PermissionDenied: The user does not have permission to perform this action.

addAsync(categories, callback)

Adds categories to the master list on a mailbox. Each category must have a unique name but multiple categories can use the same color.

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

Parameters

categories
CategoryDetails[]

The categories to be added to the master list on the mailbox.

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: ReadWriteMailbox

Applicable Outlook mode: Compose or Read

Errors:

  • DuplicateCategory: One of the categories provided is already in the master category list.

  • PermissionDenied: The user does not have permission to perform this action.

Examples

var masterCategoriesToAdd = [
    {
        "displayName": "Urgent!",
        "color": Office.MailboxEnums.CategoryColor.Preset0
    }
];

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

getAsync(options, callback)

Gets the master list of categories on a mailbox.

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: ReadWriteMailbox

Applicable Outlook mode: Compose or Read

getAsync(callback)

Gets the master list of categories on a mailbox.

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: ReadWriteMailbox

Applicable Outlook mode: Compose or Read

Examples

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

removeAsync(categories, options, callback)

Removes categories from the master list on a mailbox.

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

Parameters

categories
string[]

The categories to be removed from the master list on the mailbox.

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: ReadWriteMailbox

Applicable Outlook mode: Compose or Read

Errors:

  • PermissionDenied: The user does not have permission to perform this action.

removeAsync(categories, callback)

Removes categories from the master list on a mailbox.

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

Parameters

categories
string[]

The categories to be removed from the master list on the mailbox.

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: ReadWriteMailbox

Applicable Outlook mode: Compose or Read

Errors:

  • PermissionDenied: The user does not have permission to perform this action.

Examples

var masterCategoriesToRemove = ["Urgent!"];

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