addressBooks.provider API

The address book provider API allows to add address books, which are not stored or cached by Thunderbird itself, but are handled completely by the extension. Address books created by the this API will forward all access requests to the WebExtension.

Possible use cases include:

Implementing a custom storage.

Implementing search-only address books that query a remote server.

So far, only the API for search-only address books has been implemented.

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



Read and modify your address books and contacts.

Note

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

Events

onSearchRequest

– [Added in TB 91]

Registering this listener will create a read-only address book, similar to an LDAP address book. When selecting this address book, users will first see no contacts, but they can search for contacts, which will fire this event. Contacts returned by the listener callback will be displayed as contact cards in the address book. Several listeners can be registered, to create multiple address books.

The event also fires for each registered listener (for each created read-only address book), when users type something into the mail composer’s To: field, or into similar fields like the calendar meeting attendees field. Contacts returned by the listener callback will be added to the autocomplete results in the dropdown of that field.

Example:

messenger.addressBooks.provider.onSearchRequest.addListener(
  async (node, searchString, query) => {
    const response = await fetch(
      "https://people.acme.com/?query=" + searchString
    );
    const json = await response.json();
    return {
      isCompleteResult: true,
      // Return an array of ContactProperties as results.
      results: json.map(contact => ({
        DisplayName: contact.name,
        PrimaryEmail: contact.email,
      })),
    };
  },
  {
    addressBookName: "ACME employees",
    isSecure: true,
  }
);