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], searchString)

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

Parameters
[parentId]
(string)
The ID of the address book to search. If not specified, all address books are searched.
searchString
(string)
One or more space-separated terms to search for.
Return type (Promise)
array of ContactNode
Required permissions
  • addressBooks

get(id)

Gets a single contact.

Parameters
id
(string)
Return type (Promise)
ContactNode
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.
properties
(ContactProperties)
Return type (Promise)
string
The ID of the new contact.
Required permissions
  • addressBooks

update(id, properties)

Edits the properties of a contact. To remove a property, specify it as null.

Parameters
id
(string)
properties
(ContactProperties)
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(node, id)

Fired when a contact is created.

Parameters for event listeners
node
(ContactNode)
id
(string)
Required permissions
  • addressBooks

onUpdated(node)

Fired when a contact is changed.

Parameters for event listeners
node
(ContactNode)
Required permissions
  • addressBooks

onDeleted(parentId, id)

Fired when a contact is removed from an address book.

Parameters for event listeners
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
(ContactProperties)
type
(NodeType)
Always set to contact.
[parentId]
(string)
The id of the parent object.
[readOnly]
(boolean)
Indicates if the object is read-only. Currently this returns false in all cases, as read-only address books are ignored by the API.

ContactProperties

A set of properties for a particular contact. For a complete list of properties that Thunderbird uses, see https://hg.mozilla.org/comm-central/file/tip/mailnews/addrbook/public/nsIAbCard.idl

It is also possible to store custom properties. The custom property name however may only use a to z, A to Z, 1 to 9 and underscores.

object