addressBooks API

The addressBooks API, also including the contacts API and mailingLists API namespaces, first appeared in Thunderbird 64.

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 messenger.addressBooks.*.

Functions

openUI()

Opens the address book user interface.

Required permissions

  • addressBooks

closeUI()

Closes the address book user interface.

Required permissions

  • addressBooks

list([complete])

Gets a list of the user’s address books, optionally including all contacts and mailing lists.

Changes in Thunderbird 85

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

Parameters

[complete]

(boolean)

If set to true, results will include contacts and mailing lists for each address book.

Return type (Promise)

array of AddressBookNode

Required permissions

  • addressBooks

get(id, [complete])

Gets a single address book, optionally including all contacts and mailing lists.

Parameters

id

(string)

[complete]

(boolean)

If set to true, results will include contacts and mailing lists for this address book.

Return type (Promise)

Required permissions

  • addressBooks

create(properties)

Creates a new, empty address book.

Parameters

properties

(object)

name

(string)

Return type (Promise)

string

The id of the new address book.

Required permissions

  • addressBooks

update(id, properties)

Renames an address book.

Parameters

id

(string)

properties

(object)

name

(string)

Required permissions

  • addressBooks

delete(id)

Removes an address book, and all associated contacts and mailing lists.

Parameters

id

(string)

Required permissions

  • addressBooks

Events

onCreated

Fired when an address book is created.

Parameters for onCreated.addListener(listener)

listener(node)

A function that will be called when this event occurs.

Parameters passed to the listener function

Required permissions

  • addressBooks

onUpdated

Fired when an address book is renamed.

Parameters for onUpdated.addListener(listener)

listener(node)

A function that will be called when this event occurs.

Parameters passed to the listener function

Required permissions

  • addressBooks

onDeleted

Fired when an addressBook is deleted.

Parameters for onDeleted.addListener(listener)

listener(id)

A function that will be called when this event occurs.

Parameters passed to the listener function

id

(string)

Required permissions

  • addressBooks

Types

AddressBookNode

A node representing 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.

name

(string)

type

Always set to addressBook.

[contacts]

(array of ContactNode)

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

[mailingLists]

(array of MailingListNode)

A list of mailingLists in this node’s address book.

[parentId]

(string)

The id of the parent object.

[readOnly]

(boolean)

Indicates if the object is read-only.

[remote]

(boolean)

– [Added in TB 91]

Indicates if the address book is accessed via remote look-up.

NodeType

Indicates the type of a Node.

string

Supported values:

addressBook

contact

mailingList