Get and set categories

In Outlook, a user can apply categories to messages and appointments as a means of organizing their mailbox data. The user defines the master list of color-coded categories for their mailbox, and can then apply one or more of those categories to any message or appointment item. Each category in the master list is represented by the name and color that the user specifies. You can use the Office JavaScript API to manage the categories master list on the mailbox and the categories applied to an item.

Try it out

Try interactive samples to learn how to manage categories with an Outlook add-in. Install the Script Lab for Outlook add-in then try out the following sample snippets.

• Work with the categories master list
• Work with item categories

To learn more about Script Lab, see Explore Office JavaScript API using Script Lab.

Manage categories in the master list

Only categories in the master list of your mailbox can be applied to a message or appointment. You can use the Office JavaScript API to add, get, and remove master categories.

Prerequisite

To manage the categories master list, your add-in must request the read/write mailbox permission in its manifest. The markup varies depending on the type of manifest your add-in uses.

• Add-in only manifest: Set the <Permissions> element to ReadWriteMailbox.
• Unified manifest for Microsoft 365: Set the "name" property of an object in the "authorization.permissions.resourceSpecific" array to "Mailbox.ReadWrite.User".

Add master categories

The following example shows how to add a category named "Urgent!" to the master list by calling addAsync on mailbox.masterCategories.

const 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);
    }
});

Get master categories

The following example shows how to get the list of categories by calling getAsync on mailbox.masterCategories.

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

Remove master categories

The following example shows how to remove the category named "Urgent!" from the master list by calling removeAsync on mailbox.masterCategories.

const 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);
    }
});

Manage categories on a message or appointment

Use the item-level item.categories object to add, get, or remove categories on the current message or appointment.

Add categories to an item

The following example shows how to apply the category named "Urgent!" to the current item by calling addAsync on item.categories.

const 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);
    }
});

Get an item's categories

The following example shows how to get the categories applied to the current item by calling getAsync on item.categories.

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

Remove categories from an item

The following example shows how to remove the category named "Urgent!" from the current item by calling removeAsync on item.categories.

const 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);
    }
});

See also

• Outlook permissions
• Outlook API requirement sets
• Activate add-ins with events