management API

Hint

The management API is inherited from Firefox, and its primary documentation is maintained by Mozilla at MDN. Thunderbird implements only the subset of functions, events, and types listed here. The MDN pages may provide further details and examples, but they may also reference features that are not supported in Thunderbird.

The browser.management API provides ways to manage the list of extensions that are installed and running.

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.

management

management

Monitor extension usage and manage themes.

Functions

get(id)

– [Added in TB 56]

Returns information about the installed extension that has the given ID.

Parameters

id

The ID from an item of ExtensionInfo.

Return type (Promise)

_returns

Required permissions

  • management

getAll()

– [Added in TB 55]

Returns a list of information about installed extensions.

Note

Before version 56, only extensions whose ‘type’ is ‘theme’ are returned.

Return type (Promise)

_returns

array of ExtensionInfo

Required permissions

  • management

getSelf()

– [Added in TB 51]

Returns information about the calling extension. Note: This function can be used without requesting the ‘management’ permission in the manifest.

Return type (Promise)

_returns

install(options)

– [Added in TB 63]

Installs and enables a theme extension from the given url.

Note

The installable file pointed to by url must be a theme, and not a normal browser extension.

Parameters

options

options

(object)

url

url

URL pointing to the XPI file on addons.mozilla.org or similar.

hash

[hash]

(string, optional)

A hash of the XPI file, using sha256 or stronger.

Return type (Promise)

_returns

object

id

Required permissions

  • management

setEnabled(id, enabled)

– [Added in TB 55]

Enables or disables the given add-on.

Note

Only extensions whose ‘type’ is ‘theme’ can be enabled and disabled.

Parameters

id

id

(string)

ID of the add-on to enable/disable.

enabled

enabled

(boolean)

Whether to enable or disable the add-on.

Required permissions

  • management

uninstallSelf([options])

– [Added in TB 51]

Uninstalls the calling extension. Note: This function can be used without requesting the ‘management’ permission in the manifest.

Parameters

options

[options]

(object, optional)

dialogMessage

[dialogMessage]

(string, optional)

The message to display to a user when being asked to confirm removal of the extension.

showConfirmDialog

[showConfirmDialog]

(boolean, optional)

Whether or not a confirm-uninstall dialog should prompt the user. Defaults to false.

Events

onDisabled

– [Added in TB 55]

Fired when an addon has been disabled.

Note

Before version 56, only extensions whose type is ‘theme’ are supported.

Parameters for onDisabled.addListener(listener)

listener(info)

listener(info)

A function that will be called when this event occurs.

Parameters passed to the listener function

info

Required permissions

  • management

onEnabled

– [Added in TB 55]

Fired when an addon has been enabled.

Note

Before version 56, only extensions whose type is ‘theme’ are supported.

Parameters for onEnabled.addListener(listener)

listener(info)

listener(info)

A function that will be called when this event occurs.

Parameters passed to the listener function

info

Required permissions

  • management

onInstalled

– [Added in TB 55]

Fired when an addon has been installed.

Note

Before version 56, only extensions whose type is ‘theme’ are supported.

Parameters for onInstalled.addListener(listener)

listener(info)

listener(info)

A function that will be called when this event occurs.

Parameters passed to the listener function

info

Required permissions

  • management

onUninstalled

– [Added in TB 55]

Fired when an addon has been uninstalled.

Note

Before version 56, only extensions whose type is ‘theme’ are supported.

Note

This event is not fired when the extension is in the “pending uninstall” state. The event is fired as expected once the extension is completely removed (for example, when the about:addons tab is closed).

Parameters for onUninstalled.addListener(listener)

listener(info)

listener(info)

A function that will be called when this event occurs.

Parameters passed to the listener function

info

Required permissions

  • management

Types

ExtensionDisabledReason

A reason the item is disabled.

string

Supported values:

permissions_increase

permissions_increase

unknown

unknown

ExtensionID

string

or

string

ExtensionInfo

– [Added in TB 51]

Information about an installed extension.

object

description

description

(string)

The description of this extension.

enabled

enabled

(boolean)

Whether it is currently enabled or disabled.

id

id

(string)

The extension’s unique identifier.

installType

installType

How the extension was installed.

mayDisable

mayDisable

(boolean)

Whether this extension can be disabled or uninstalled by the user.

name

name

(string)

The name of this extension.

optionsUrl

optionsUrl

(string)

The url for the item’s options page, if it has one.

type

type

– [Added in TB 55]

The type of this extension, ‘extension’ or ‘theme’.

version

version

(string)

The version of this extension.

disabledReason

[disabledReason]

A reason the item is disabled.

homepageUrl

[homepageUrl]

(string, optional)

The URL of the homepage of this extension.

hostPermissions

[hostPermissions]

(array of string, optional)

Returns a list of host based permissions.

icons

[icons]

(array of IconInfo, optional)

A list of icon information. Note that this just reflects what was declared in the manifest, and the actual image at that url may be larger or smaller than what was declared, so you might consider using explicit width and height attributes on img tags referencing these images. See the manifest documentation on icons for more details.

permissions

[permissions]

(array of string, optional)

Returns a list of API based permissions.

shortName

[shortName]

(string, optional)

A short version of the name of this extension.

updateUrl

[updateUrl]

(string, optional)

The update URL of this extension.

versionName

[versionName]

(string, optional)

The version name of this extension if the manifest specified one.

ExtensionInstallType

How the extension was installed. One of development: The extension was loaded unpacked in developer mode, normal: The extension was installed normally via an .xpi file, sideload: The extension was installed by other software on the machine, admin: The extension was installed by policy, other: The extension was installed by other means.

string

Supported values:

admin

admin

development

development

normal

normal

other

other

sideload

sideload

ExtensionType

The type of this extension, ‘extension’ or ‘theme’.

string

Supported values:

extension

extension

theme

theme

HttpURL

string

IconInfo

Information about an icon belonging to an extension.

object

size

size

(integer)

A number representing the width and height of the icon. Likely values include (but are not limited to) 128, 48, 24, and 16.

url

url

(string)

The URL for this icon image. To display a grayscale version of the icon (to indicate that an extension is disabled, for example), append ?grayscale=true to the URL.