Office.Categories interface
Represents the categories on an item.
In Outlook, a user can tag 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 and new Outlook on Windows, you can't use the API to manage categories applied to a message in Compose mode.
Remarks
Minimum permission level: read item
Applicable Outlook mode: Compose or Read
Methods
| add |
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. |
| add |
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. |
| get |
Gets an item's categories. Important:
|
| get |
Gets an item's categories. Important:
|
| remove |
Removes categories from an item. |
| remove |
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
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 function.
- 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.
Returns
void
Remarks
Minimum permission level: read/write item
Applicable Outlook mode: Compose or Read
Important: In Outlook on the web and new Outlook on Windows, you can't use the API to manage categories applied to a message or appointment item in Compose mode.
Errors:
InvalidCategory: Invalid categories were provided.
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/45-categories/work-with-categories.yaml
// Note: In order for you to successfully add a category,
// it must be in the mailbox categories master list.
Office.context.mailbox.masterCategories.getAsync(function(asyncResult) {
if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
const masterCategories = asyncResult.value;
if (masterCategories && masterCategories.length > 0) {
// Grab the first category from the master list.
const categoryToAdd = [masterCategories[0].displayName];
Office.context.mailbox.item.categories.addAsync(categoryToAdd, function(asyncResult) {
if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
console.log(`Successfully assigned category '${categoryToAdd}' to item.`);
} else {
console.log("categories.addAsync call failed with error: " + asyncResult.error.message);
}
});
} else {
console.log("There are no categories in the master list on this mailbox. You can add categories using Office.context.mailbox.masterCategories.addAsync.");
}
} else {
console.error(asyncResult.error);
}
});
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
Optional. When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult.
Returns
void
Remarks
Minimum permission level: read/write item
Applicable Outlook mode: Compose or Read
Important: In Outlook on the web and new Outlook on Windows, you can't use the API to manage categories applied to a message or appointment item in Compose mode.
Errors:
InvalidCategory: Invalid categories were provided.
getAsync(options, callback)
Gets an item's categories.
Important:
If there are no categories on the item,
nullor an empty array will be returned depending on the Outlook version so make sure to handle both cases.In Outlook on the web and new Outlook on Windows, you can't use the API to manage categories applied to a message in Compose mode.
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 function.
- callback
-
(asyncResult: Office.AsyncResult<Office.CategoryDetails[]>) => void
When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. If getting categories fails, the asyncResult.error property will contain an error code.
Returns
void
Remarks
Minimum permission level: read item
Applicable Outlook mode: Compose or Read
getAsync(callback)
Gets an item's categories.
Important:
If there are no categories on the item,
nullor an empty array will be returned depending on the Outlook version so make sure to handle both cases.In Outlook on the web and new Outlook on Windows, you can't use the API to manage categories applied to a message in Compose mode.
getAsync(callback: (asyncResult: Office.AsyncResult<CategoryDetails[]>) => void): void;Parameters
- callback
-
(asyncResult: Office.AsyncResult<Office.CategoryDetails[]>) => void
When the method completes, the function passed in the callback parameter is called with a single parameter of type Office.AsyncResult. If getting categories fails, the asyncResult.error property will contain an error code.
Returns
void
Remarks
Minimum permission level: read item
Applicable Outlook mode: Compose or Read
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/45-categories/work-with-categories.yaml
Office.context.mailbox.item.categories.getAsync(function(asyncResult) {
if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
const categories = asyncResult.value;
if (categories && categories.length > 0) {
console.log("Categories assigned to this item:");
console.log(JSON.stringify(categories));
} else {
console.log("There are no categories assigned to this item.");
}
} else {
console.error(asyncResult.error);
}
});
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
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 function.
- 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.
Returns
void
Remarks
Minimum permission level: read/write item
Applicable Outlook mode: Compose or Read
Important: In Outlook on the web and new Outlook on Windows, you can't use the API to manage categories applied to a message or appointment item in Compose mode.
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/45-categories/work-with-categories.yaml
Office.context.mailbox.item.categories.getAsync(function(asyncResult) {
if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
const categories = asyncResult.value;
if (categories && categories.length > 0) {
// Grab the first category assigned to this item.
const categoryToRemove = [categories[0].displayName];
Office.context.mailbox.item.categories.removeAsync(categoryToRemove, function(asyncResult) {
if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
console.log(`Successfully unassigned category '${categoryToRemove}' from this item.`);
} else {
console.log("categories.removeAsync call failed with error: " + asyncResult.error.message);
}
});
} else {
console.log("There are no categories assigned to this item.");
}
} else {
console.error(asyncResult.error);
}
});
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
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.
Returns
void
Remarks
Minimum permission level: read/write item
Applicable Outlook mode: Compose or Read
Important: In Outlook on the web and new Outlook on Windows, you can't use the API to manage categories applied to a message or appointment item in Compose mode.
Office Add-ins