title | description | ms.date | ms.topic | ms.localizationpriority |
---|---|---|---|---|
Get and set categories |
How to manage categories on mailbox and item. |
04/12/2024 |
how-to |
medium |
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.
Note
Support for this feature was introduced in requirement set 1.8. See clients and platforms that support this requirement set.
Only categories in the master list on your mailbox are available for you to apply to a message or appointment. You can use the API to add, get, and remove master categories.
Important
For the add-in to manage the categories master list, it must request the read/write mailbox permission in the manifest. The markup varies depending on the type of manifest.
- XML 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".
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);
}
});
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));
});
}
});
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);
}
});
You can use the API to add, get, and remove categories for a message or appointment item.
Important
Only categories in the master list on your mailbox are available for you to apply to a message or appointment. See the earlier section Manage categories in the master list for more information.
In Outlook on the web or new Outlook on Windows (preview), you can't use the API to manage categories on a message in Compose mode.
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);
}
});
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));
});
}
});
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);
}
});