≡ messages.tags API

≡ Add-on developer resources

≡ Guides

messages.tags API

The messages.tags API allows to manage the user’s message tags.

Permissions

The following permissions influence the behavior of the API. Depending on which permissions are requested, additional methods might be available, or certain data may be included in responses.

Hint

Request permissions only when needed. Unnecessary requests may result in rejection during ATN review.

accountsRead

accountsRead

See your mail accounts, their identities and their folders.

messagesTags

messagesTags

Create, modify and delete message tags.

messagesTagsList

messagesTagsList

List message tags.

Functions

create([key], tag, color, [callback])

– [Added in TB 121]

Creates a new message tag and returns the associated key. Tagging a message will store the tag’s key in the user’s message. Throws if the specified tag key is used already.

Parameters

key

[key]

(string, optional)

Unique tag identifier (will be converted to lower case). Must not include ()<>{/%*” or spaces. Will be auto-generated if not provided.

tag

tag

(string)

Human-readable tag name.

color

color

(string)

Tag color in hex format (i.e.: #000080 for navy blue).

callback

[callback]

(function, optional)

– [Added in TB 136]

Required permissions

  • messagesTags

delete(key)

– [Added in TB 121]

Deletes a message tag, removing it from the list of known tags. Its key will not be removed from tagged messages, but they will appear untagged. Recreating a deleted tag, will make all former tagged messages appear tagged again.

Parameters

key

key

(string)

Unique tag identifier (will be converted to lower case). Must not include ()<>{/%*” or spaces.

Required permissions

  • messagesTags

list()

– [Added in TB 121]

Returns a list of tags that can be set on messages, and their human-friendly name, colour, and sort order.

Return type (Promise)

_returns

array of MessageTag

Required permissions

  • messagesTagsList

update(key, updateProperties)

– [Added in TB 121]

Updates a message tag. Throws if the specified tag key does not exist.

Parameters

key

key

(string)

Unique tag identifier (will be converted to lower case). Must not include ()<>{/%*” or spaces.

updateProperties

updateProperties

(MessageTagProperties)

Required permissions

  • messagesTags

Events

onCreated

– [Added in TB 136]

Fired when a new message tag has been created.

Parameters for onCreated.addListener(listener)

listener(tag)

listener(tag)

A function that will be called when this event occurs.

Parameters passed to the listener function

tag

tag

(MessageTag)

Required permissions

  • messagesTagsList

onDeleted

– [Added in TB 136]

Fired when a message tag has been deleted.

Parameters for onDeleted.addListener(listener)

listener(key)

listener(key)

A function that will be called when this event occurs.

Parameters passed to the listener function

key

key

(string)

Unique tag identifier of the deleted message tag.

Required permissions

  • accountsRead

onUpdated

– [Added in TB 136]

Fired when one or more properties of a message tag have been updated.

Parameters for onUpdated.addListener(listener)

listener(key, changedProperties, oldProperties)

listener(key, changedProperties, oldProperties)

A function that will be called when this event occurs.

Parameters passed to the listener function

key

key

(string)

Unique tag identifier of the updated message tag.

changedProperties

changedProperties

(MessageTagProperties)

The changed message tag properties.

oldProperties

oldProperties

(MessageTagProperties)

The old values of the changed message tag properties.

Required permissions

  • messagesTagsList

Types

MessageTag

– [Added in TB 121]

object

color

color

(string)

Tag color in upper case hex format (i.e.: #000080 for navy blue).

key

key

(string)

Unique tag identifier.

ordinal

ordinal

(string)

A custom sort string.

tag

tag

(string)

Human-readable tag name.

MessageTagProperties

– [Added in TB 136]

object

color

[color]

(string, optional)

Tag color in upper case hex format (i.e.: #000080 for navy blue).

ordinal

[ordinal]

(string, optional)

A custom sort string.

tag

[tag]

(string, optional)

Human-readable tag name.

TagsDetail

– [Added in TB 121]

Used for filtering messages by tag in various methods. Note that functions using this type may have a partial implementation.

object

mode

mode

(string)

Whether all of the tag filters must apply, or any of them.

Supported values:

all

all

any

any

tags

tags

(object)

A dictionary object with one or more filter condition as key-value pairs, the key being the tag to filter on, and the value being a boolean expression, requesting whether a message must include (true) or exclude (false) the tag. For a list of available tags, call the list() method.