≡ addressBooks.contacts API

• Permissions

• Functions

• Events

• Types

≡ Add-on developer resources

• Introduction to add-on development

• "Hello world" extension tutorial

• Developer community

• Sample extensions (Github)

• Using Promises

• Additional resources on DTN

≡ Guides

• Strategies to avoid using innerHTML

• Working with WebExtension events

• Using runtime messages

• Working with message lists

• Working with vCard contacts

• Converting extensions to Manifest V3

addressBooks.contacts API

The contacts API allows to access and manage the user’s contacts.

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

addressBooks

Read and modify your address books and contacts.

Note

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

Functions

create(parentId, vCard)

– [Added in TB 127]

Adds a new contact to the address book with the id parentId.

Parameters

parentId

parentId

(string)

vCard

vCard

(string)

The vCard for the new contact. If it includes an (optional) id and an existing contact has this id already, an exception is thrown.

Return type (Promise)

_returns

string

– [Added in TB 128]

The ID of the new contact.

Required permissions

• addressBooks

delete(id)

– [Added in TB 127]

Removes a contact from the address book. The contact is also removed from any mailing lists it is a member of.

Parameters

id

id

(string)

Required permissions

• addressBooks

get(id)

– [Added in TB 127]

Gets a single contact.

Parameters

id

id

(string)

Return type (Promise)

_returns

ContactNode

Required permissions

• addressBooks

getPhoto(id)

– [Added in TB 127]

Gets the photo associated with this contact. Returns null, if no photo is available.

Parameters

id

id

(string)

Return type (Promise)

_returns

File or null

Required permissions

• addressBooks

list(parentId)

– [Added in TB 127]

Gets all the contacts in the address book with the id parentId.

Parameters

parentId

parentId

(string)

Return type (Promise)

_returns

array of ContactNode

Required permissions

• addressBooks

query(queryInfo)

– [Added in TB 127]

Gets all contacts matching queryInfo.

Parameters

queryInfo

queryInfo

(QueryInfo)

Return type (Promise)

_returns

array of ContactNode

Required permissions

• addressBooks

setPhoto(id, file)

– [Added in TB 127]

Sets the photo associated with this contact.

Parameters

id

id

(string)

file

file

(File)

Required permissions

• addressBooks

update(id, vCard)

– [Added in TB 127]

Updates a contact.

Parameters

id

id

(string)

vCard

vCard

(string)

The updated vCard for the contact.

Required permissions

• addressBooks

Events

onCreated

– [Added in TB 127]

Fired when a contact 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

(ContactNode)

Required permissions

• addressBooks

onDeleted

– [Added in TB 127]

Fired when a contact is removed from an address book.

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

onUpdated

– [Added in TB 127]

Fired when a contact is changed.

Parameters for onUpdated.addListener(listener)

listener(node, oldVCard)

listener(node, oldVCard)

A function that will be called when this event occurs.

Parameters passed to the listener function

node

node

(ContactNode)

oldVCard

oldVCard

(string)

Required permissions

• addressBooks

Types

ContactNode

– [Added in TB 127]

A node representing a contact in an address book.

object

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.

type

type

(NodeType)

Always set to contact.

vCard

vCard

(string)

– [Added in TB 128]

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)

Indicates if the object came from a remote address book.

ContactProperties

– [Added in TB 127]

A set of individual properties for a particular contact, and its vCard string. Further information can be found in Working with vCard contacts.

object

PropertyChange

– [Added in TB 127]

A dictionary of changed properties. Keys are the property name that changed, values are an object containing oldValue and newValue. Values can be either a string or null.

object

QueryInfo

– [Added in TB 127]

Object defining a query for query(queryInfo).

object

includeLocal

[includeLocal]

(boolean, optional)

Whether to include results from local address books. Defaults to true.

includeReadOnly

[includeReadOnly]

(boolean, optional)

Whether to include results from read-only address books. Defaults to true.

includeReadWrite

[includeReadWrite]

(boolean, optional)

Whether to include results from read-write address books. Defaults to true.

includeRemote

[includeRemote]

(boolean, optional)

Whether to include results from remote address books. Defaults to true.

parentId

[parentId]

(string, optional)

The id of the address book to search. If not specified, all address books are searched.

searchString

[searchString]

(string, optional)

One or more space-separated terms to search for in predefined contact fields (defined by the preference mail.addr_book.quicksearchquery.format).