Office.Categories interface

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 and new Outlook on Windows, 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 and new Outlook on Windows, 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 and new Outlook on Windows, 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 and new Outlook on Windows, 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 and new Outlook on Windows, 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 and new Outlook on Windows, 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 and new Outlook on Windows, 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 and new Outlook on Windows, 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 and new Outlook on Windows, 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 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

[ 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 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

[ 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 and new Outlook on Windows, 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 and new Outlook on Windows, 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