≡ messages.tags API
≡ Add-on developer resources
messages.tags API
The messages.tags API allows to manage the user’s message tags.
Permissions
messagesTags
Create, modify and delete message tags
messagesTagsList
List message tags
messagesModifyPermanent
Permanently modify the source of your messages (including headers, body and attachments)
Functions
create([key], tag, color, [callback])
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]
(string, optional)
Unique tag identifier (will be converted to lower case). Must not include ()<>{/%*” or spaces. Will be auto-generated if not provided.
tag
(string)
Human-readable tag name.
color
(string)
Tag color in hex format (i.e.: #000080 for navy blue).
[callback]
(function, optional)
Required permissions
messagesTags
delete(key)
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
(string)
Unique tag identifier (will be converted to lower case). Must not include ()<>{/%*” or spaces.
Required permissions
messagesTags
list()
Returns a list of tags that can be set on messages, and their human-friendly name, colour, and sort order.
Return type (Promise)
array of MessageTag
Required permissions
messagesTagsList
update(key, updateProperties)
Updates a message tag. Throws if the specified tag key does not exist.
Parameters
key
(string)
Unique tag identifier (will be converted to lower case). Must not include ()<>{/%*” or spaces.
Required permissions
messagesTags
Events
onCreated
Fired when a new message tag has been created.
Parameters for onCreated.addListener(listener)
listener(tag)
A function that will be called when this event occurs.
Parameters passed to the listener function
Required permissions
messagesTagsList
onDeleted
Fired when a message tag has been deleted.
Parameters for onDeleted.addListener(listener)
listener(key)
A function that will be called when this event occurs.
Parameters passed to the listener function
key
(string)
Unique tag identifier of the deleted message tag.
Required permissions
accountsRead
onUpdated
Fired when one or more properties of a message tag have been updated.
Parameters for onUpdated.addListener(listener)
listener(key, changedProperties, oldProperties)
A function that will be called when this event occurs.
Parameters passed to the listener function
key
(string)
Unique tag identifier of the updated message tag.
The changed message tag properties.
The old values of the changed message tag properties.
Required permissions
messagesTagsList
Types
MessageTag
object
color
(string)
Tag color in upper case hex format (i.e.: #000080 for navy blue).
key
(string)
Unique tag identifier.
ordinal
(string)
A custom sort string.
tag
(string)
Human-readable tag name.
MessageTagProperties
object
[color]
(string, optional)
Tag color in upper case hex format (i.e.: #000080 for navy blue).
[ordinal]
(string, optional)
A custom sort string.
[tag]
(string, optional)
Human-readable tag name.
TagsDetail
Used for filtering messages by tag in various methods. Note that functions using this type may have a partial implementation.
object
mode
(string)
Whether all of the tag filters must apply, or any of them.
Supported values:
all
any
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.