Edit

Office.Categories interface

  • Reference
Package:
outlook

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, you can't use the API to manage categories applied to a message in Compose mode.

Remarks

[ API set: Mailbox 1.8 ]

Minimum permission level: read item

Applicable Outlook mode: Compose or Read

Methods

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.

Important: In Outlook on the web, you can't use the API to manage categories applied to a message or appointment item in Compose mode.
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.

Important: In Outlook on the web, you can't use the API to manage categories applied to a message or appointment item in Compose mode.
getAsync(options, callback)

Gets an item's categories.

Important:

  • If there are no categories on the item, null or an empty array will be returned depending on the Outlook version so make sure to handle both cases.

  • In Outlook on the web, you can't use the API to manage categories applied to a message in Compose mode.
getAsync(callback)

Gets an item's categories.

Important:

  • If there are no categories on the item, null or an empty array will be returned depending on the Outlook version so make sure to handle both cases.

  • In Outlook on the web, you can't use the API to manage categories applied to a message in Compose mode.
removeAsync(categories, options, callback)

Removes categories from an item.

Important: In Outlook on the web, you can't use the API to manage categories applied to a message in Compose mode.
removeAsync(categories, callback)

Removes categories from an item.

Important: In Outlook on the web, you can't use the API to manage categories applied to a message in Compose mode.

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.

Important: In Outlook on the web, you can't use the API to manage categories applied to a message or appointment item in Compose mode.

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

[ API set: Mailbox 1.8 ]

Minimum permission level: read/write item

Applicable Outlook mode: Compose or Read

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.

Important: In Outlook on the web, you can't use the API to manage categories applied to a message or appointment item in Compose mode.

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

[ API set: Mailbox 1.8 ]

Minimum permission level: read/write item

Applicable Outlook mode: Compose or Read

Errors:

  • InvalidCategory: Invalid categories were provided.

getAsync(options, callback)

Gets an item's categories.

Important:

  • If there are no categories on the item, null or an empty array will be returned depending on the Outlook version so make sure to handle both cases.

  • In Outlook on the web, 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

[ API set: Mailbox 1.8 ]

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, null or an empty array will be returned depending on the Outlook version so make sure to handle both cases.

  • In Outlook on the web, 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

[ API set: Mailbox 1.8 ]

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.

Important: In Outlook on the web, you can't use the API to manage categories applied to a message in Compose mode.

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

[ API set: Mailbox 1.8 ]

Minimum permission level: read/write 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) {
      // 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.

Important: In Outlook on the web, you can't use the API to manage categories applied to a message in Compose mode.

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

[ API set: Mailbox 1.8 ]

Minimum permission level: read/write item

Applicable Outlook mode: Compose or Read