mailingLists API

The mailingLists API allows to access and manage the user’s mailing lists.

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.

addressBooks



Read and modify your address books and contacts.

Note

The permission addressBooks is required to use messenger.mailingLists.*.

Functions

addMember(id, contactId)

– [Added in TB 64]

Adds a contact to the mailing list with id id. If the contact and mailing list are in different address books, the contact will also be copied to the list’s address book.

Parameters

id

id

(string)



contactId

contactId

(string)



Required permissions

addressBooks

create(parentId, properties)

– [Added in TB 64]

Creates a new mailing list in the address book with id parentId.

Parameters

parentId

parentId

(string)



properties

properties

(object)



name

name

(string)



description

[description]

(string, optional)



nickName

[nickName]

(string, optional)



Return type (Promise)

_returns

string

– [Added in TB 96]



The ID of the new mailing list.

Required permissions

addressBooks

delete(id)

– [Added in TB 64]

Removes the mailing list.

Parameters

id

id

(string)



Required permissions

addressBooks

get(id)

– [Added in TB 64]

Gets a single mailing list.

Parameters

id

id

(string)



Return type (Promise)

_returns

MailingListNode

– [Added in TB 96]



Required permissions

addressBooks

list(parentId)

– [Added in TB 64]

Gets all the mailing lists in the address book with id parentId.

Parameters

parentId

parentId

(string)



Return type (Promise)

_returns

array of MailingListNode

– [Added in TB 96]



Required permissions

addressBooks

listMembers(id)

– [Added in TB 64]

Gets all contacts that are members of the mailing list with id id.

Parameters

id

id

(string)



Return type (Promise)

_returns

array of ContactNode

– [Added in TB 96]



Required permissions

addressBooks

removeMember(id, contactId)

– [Added in TB 64]

Removes a contact from the mailing list with id id. This does not delete the contact from the address book.

Parameters

id

id

(string)



contactId

contactId

(string)



Required permissions

addressBooks

update(id, properties)

– [Added in TB 64]

Edits the properties of a mailing list.

Parameters

id

id

(string)



properties

properties

(object)



name

name

(string)



description

[description]

(string, optional)



nickName

[nickName]

(string, optional)



Required permissions

addressBooks

Events

onCreated

– [Added in TB 64]

Fired when a mailing list is created.

Parameters for onCreated.addListener(listener)

listener(node)

listener(node)



A function that will be called when this event occurs.

Parameters passed to the listener function

node

node

(MailingListNode)



Required permissions

addressBooks

onDeleted

– [Added in TB 64]

Fired when a mailing list is deleted.

Parameters for onDeleted.addListener(listener)

listener(parentId, id)

listener(parentId, id)



A function that will be called when this event occurs.

Parameters passed to the listener function

parentId

parentId

(string)



id

id

(string)



Required permissions

addressBooks

onMemberAdded

– [Added in TB 64]

Fired when a contact is added to the mailing list.

Parameters for onMemberAdded.addListener(listener)

listener(node)

listener(node)



A function that will be called when this event occurs.

Parameters passed to the listener function

node

node

(ContactNode)



Required permissions

addressBooks

onMemberRemoved

– [Added in TB 64]

Fired when a contact is removed from the mailing list.

Parameters for onMemberRemoved.addListener(listener)

listener(parentId, id)

listener(parentId, id)



A function that will be called when this event occurs.

Parameters passed to the listener function

parentId

parentId

(string)



id

id

(string)



Required permissions

addressBooks

onUpdated

– [Added in TB 64]

Fired when a mailing list is changed.

Parameters for onUpdated.addListener(listener)

listener(node)

listener(node)



A function that will be called when this event occurs.

Parameters passed to the listener function

node

node

(MailingListNode)



Required permissions

addressBooks

Types

MailingListNode

– [Added in TB 64]

A node representing a mailing list.

object

description

description

(string)



id

id

(string)



The unique identifier for the node. IDs are unique within the current profile, and they remain valid even after the program is restarted.

name

name

(string)



nickName

nickName

(string)



type

type

(NodeType)



Always set to mailingList.

contacts

[contacts]

(array of ContactNode, optional)



A list of contacts held by this node’s address book or mailing list.

parentId

[parentId]

(string, optional)



The id of the parent object.

readOnly

[readOnly]

(boolean, optional)



Indicates if the object is read-only.

remote

[remote]

(boolean, optional)

– [Added in TB 91]



Indicates if the object came from a remote address book.