contacts

The address books API, also including the addressBooks and mailingLists namespaces, first appeared in Thunderbird 64. The quickSearch function was added in Thunderbird 68.

The Address Books sample extension uses this API.

Permissions

addressBooks

Read and modify your address books and contacts

Note

The permission addressBooks is required to use contacts.

Functions

list(parentId)

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

Parameters

parentId

(string)

Return type (Promise)

array of ContactNode

Required permissions

  • addressBooks

quickSearch([parentId], queryInfo)

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

Changes in Thunderbird 91

Second parameter can be a QueryInfo. A single string is still supported and used as queryInfo.searchString.

Changes in Thunderbird 85

Read-only address books are now returned as well as read-write books.

Parameters

[parentId]

(string)

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

queryInfo

(string or QueryInfo)

Return type (Promise)

array of ContactNode

Required permissions

  • addressBooks

get(id)

Gets a single contact.

Parameters

id

(string)

Return type (Promise)

Required permissions

  • addressBooks

create(parentId, [id], properties)

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

Parameters

parentId

(string)

[id]

(string)

Assigns the contact an id. If an existing contact has this id, an exception is thrown. Note: Deprecated, the card’s id should be specified in the vCard string instead.

properties

The properties object for the new contact. If it includes a vCard member, all specified legacy properties are ignored and the new contact will be based on the provided vCard string. If a UID is specified in the vCard string, which is already used by another contact, an exception is thrown. Note: Using individual properties is deprecated, use the vCard member instead.

Return type (Promise)

string

The ID of the new contact.

Required permissions

  • addressBooks

update(id, properties)

Updates a contact.

Parameters

id

(string)

properties

An object with properties to update the specified contact. Individual properties are removed, if they are set to null. If the provided object includes a vCard member, all specified legacy properties are ignored and the details of the contact will be replaced by the provided vCard. Changes to the UID will be ignored. Note: Using individual properties is deprecated, use the vCard member instead.

Required permissions

  • addressBooks

delete(id)

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

Parameters

id

(string)

Required permissions

  • addressBooks

Events

onCreated

Fired when a contact is created.

Parameters for onCreated.addListener(listener)

listener(node, id)

A function that will be called when this event occurs.

Parameters passed to the listener function

node

id

(string)

Required permissions

  • addressBooks

onUpdated

Fired when a contact is changed.

Parameters for onUpdated.addListener(listener)

listener(node, changedProperties)

A function that will be called when this event occurs.

Parameters passed to the listener function

node

changedProperties

– [Added in TB 83]

Required permissions

  • addressBooks

onDeleted

Fired when a contact is removed from an address book.

Parameters for onDeleted.addListener(listener)

listener(parentId, id)

A function that will be called when this event occurs.

Parameters passed to the listener function

parentId

(string)

id

(string)

Required permissions

  • addressBooks

Types

ContactNode

A node representing a contact in an address book.

object

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.

properties

type

Always set to contact.

[parentId]

(string)

The id of the parent object.

[readOnly]

(boolean)

Indicates if the object is read-only.

[remote]

(boolean)

Indicates if the object came from a remote address book.

ContactProperties

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

object

<custom properties>

(string)

Custom properties are not saved in the users vCard. Therfore, they are not transfered to the users server, if the contact is stored on a remote CardDAV server. Names of custom properties may include a-z, A-Z, 1-9 and _.

<legacy properties>

(string) Deprecated.

Legacy properties point to certain fields in the contacts vCard string and provide direct read/write access.

vCard

(string)

– [Added in TB 102]

The contacts vCard string.

PropertyChange

– [Added in TB 83]

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 91]

Object defining a query for quickSearch([parentId], queryInfo).

object

[includeLocal]

(boolean)

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

[includeReadOnly]

(boolean)

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

[includeReadWrite]

(boolean)

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

[includeRemote]

(boolean)

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

[searchString]

(string)

One or more space-separated terms to search for.