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.

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

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

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