addressBooks

The address books API, also including the contacts and mailingLists 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 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.

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(node)

Fired when an address book is created.

Parameters for event listeners
Required permissions
  • addressBooks

onUpdated(node)

Fired when an address book is renamed.

Parameters for event listeners
Required permissions
  • addressBooks

onDeleted(id)

Fired when an addressBook is deleted.

Parameters for event listeners
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. Currently this returns false in all cases, as read-only address books are ignored by the API.

NodeType

Indicates the type of a Node, which can be one of addressBook, contact, or mailingList.

string

Supported values:

addressBook
contact
mailingList