Office.MasterCategories interface
Represents the categories master list on the mailbox.
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 delegate or shared scenarios, the delegate can get the categories in the master list but can't add or remove categories.
Methods
| add |
Adds categories to the master list on a mailbox. Each category must have a unique name but multiple categories can use the same color. |
| add |
Adds categories to the master list on a mailbox. Each category must have a unique name but multiple categories can use the same color. |
| get |
Gets the master list of categories on a mailbox. |
| get |
Gets the master list of categories on a mailbox. |
| remove |
Removes categories from the master list on a mailbox. |
| remove |
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
The categories to be added to the master list on the mailbox.
- 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 mailbox
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
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/45-categories/work-with-master-categories.yaml
const masterCategoriesToAdd = [
{
displayName: "TestCategory",
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);
}
});
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
The categories to be added to the master list on the mailbox.
- 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 mailbox
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.
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 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 adding categories fails, the asyncResult.error property will contain an error code.
Returns
void
Remarks
Minimum permission level: read/write mailbox
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<Office.CategoryDetails[]>) => void
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 mailbox
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-master-categories.yaml
Office.context.mailbox.masterCategories.getAsync(function(asyncResult) {
if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
const categories = asyncResult.value;
if (categories && categories.length > 0) {
console.log("Master categories:");
console.log(JSON.stringify(categories));
} else {
console.log("There are no categories in the master list.");
}
} else {
console.error(asyncResult.error);
}
});
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
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 mailbox
Applicable Outlook mode: Compose or Read
Errors:
PermissionDenied: The user does not have permission to perform this action.
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/45-categories/work-with-master-categories.yaml
const masterCategoriesToRemove = ["TestCategory"];
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);
}
});
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
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 mailbox
Applicable Outlook mode: Compose or Read
Errors:
PermissionDenied: The user does not have permission to perform this action.