Supported WebExtension APIs

Descriptions of all WebExtension API supported by Thunderbird.

Thunderbird WebExtension APIs
Thunderbird provides the following messenger related WebExtension APIs, which are sometimes referred to as MailExtension APIs.
API
Permission
Description
​accounts​
accountsRead
Enables an extension to access information of accounts and identities configured in Thunderbird's account manager.
​addressBooks​
addressBooks
Enables an extension to access, modify, create and delete Thunderbird address books.
​browserAction​
​
Enables an extension to interact with a browser action button.

Permission info:
This API does not require a permission, but a browser_action manifest key.
Note: This API has been renamed to action in Manifest V3.
​cloudFile​
​
Enables an extension to register a cloudFile provider, which can be used to upload large attachments to a server, instead of attaching them directly to the email.
Permission info:
This API does not require a permission, but a cloudFile manifest key.
​commands​
​
The commands API adds keyboard shortcuts that can trigger actions in an extension.

Permission info:
This API does not require a permission, but a commands manifest key.
​compose​
compose
Enables an extension to open a new message compose window or react to events while the message is being composed.
​composeAction​
​
Enables an extension to interact with a compose action button.

Permission info:
This API does not require a permission, but a compose_action manifest key.
​composeScripts​
compose
Functionally is the same as the contentScripts API except that it works on the document of email messages during composition.
​contacts​
addressBooks
Enables an extension to access, modify, create and delete contacts in Thunderbird address books.
​folders​
accountsFolders
Enables an extension to access, modify, create and delete mail account folders.
​mailingLists​
addressBooks
Enables an extension to access, modify, create and delete mailing lists in Thunderbird address books.
​mailTabs​
accountsFolders
Enables an extension to interact with Thunderbird's main window.

Permission info:
The accountsFolders permission is only needed to set the currently displayed folder.
​menus​
menus,
menus.overrideContext,
accountsRead, messagesRead,
activeTab
Enables an extension to add (context-) menu entries to Thunderbird menus.

Permission info:
The menus.overrideContext permission is needed to override a default menu entry.
The accountsRead and messagesRead permissions are needed to populate the associated fields in the OnClickedData object.
The activeTab permission is (currently) needed to get advanced information for the onShown event (see bug 1664423)
​messageDisplay​
messagesRead
Enables an extension to react on and interact with the currently displayed messages.
​messageDisplayAction​
​
Enables an extension to interact with a message display action button.

Permission info:
This API does not require a permission, but a message_display_action manifest key.
​messageDisplayScripts​
messagesModify
Functionally is the same as the contentScripts API except that it works on the document of email messages being displayed.
​messages​
messagesRead,
messagesMove,
accountsRead
Enables an extension to list, search, read, copy, move and delete messages.

Permission info:
The messagesRead permission is needed to list, read, mark and tag messages.
The messagesMove permission is needed to copy, move and delete messages.
The accountsRead permission is needed by any function/event which involves folder information.
​tabs​
tabs, activeTab, compose, messageModify
Enables an extension to interact with Thunderbird's tab system. It allows to create, modify, and rearrange tabs and to communicate with scripts in tabs.

Permission info:
The tabs or activeTab permission is only needed if the url, favIconUrl or title information of tabs are accessed. The tab permission will allow access to that information in all tabs, the activeTab permission restricts that to the active tab.
Note: The activeTab permission implies the <all_urls> host permission for the active (web page -) tab.
The compose permissions is needed to call tabs.executeScript() and tabs.insertCSS() for compose tabs.
The messageModify permission is needed to call tabs.executeScript() and tabs.insertCSS() for a message display tab.
​theme​
theme
The theme API can be used to create static or dynamic Thunderbird themes. Theme experiments are supported.
​
Permission info:
The theme permission is needed to dynamically update the theme.
​windows​
tabs
Enables an extension to interact with Thunderbird's windows which can contain webpage tabs and also other window types like composer or address books that cannot contain webpage tabs. You can use this API to create, modify, and rearrange windows.

Permission info:
The tabs permission is needed to populate the url, favIconUrl and title information in the tabs member of the Window object.
You can find more information in the Thunderbird WebExtensions API documentation .
Firefox WebExtension APIs
As Thunderbird is based on Firefox, many of its WebExtension APIs can be used in Thunderbird as well. The APIs listed in the following table are known to work with Thunderbird.
The following APIs link to their MDN description pages. Please be aware, that MDN is dedicated to web browsers (not limited to Firefox). Some information listed on MDN may not apply to Thunderbird and some API methods may not be supported. Each API page should include a compatibility chart and if that includes support for Firefox, it should work in Thunderbird as well.
API
Permission
Description
​browserSettings​
browserSettings
Enables an extension to modify certain global browser settings. Because these are global settings, it's possible for extensions to conflict. See the documentation for BrowserSetting.set() for details of how conflicts are handled.
​clipboard​
clipboardWrite,
clipboardRead
Enables an extension to copy items to the system clipboard. Currently the API only supports copying images, but it's intended to support copying text and HTML in the future.

Permission info:
The clipboardRead permission is not used by this API but is listed here for completeness. To read from the clipboard, the Clipboard Web API has to be used and needs the clipboardRead permission.
​contentScripts​
​
Use this API to register content scripts to instruct the browser to insert the given content scripts into pages that match the URL patterns specified during registration. In Thunderbird, content scripts can only be used in web pages loaded into tabs.

Permission info:
This API does not require a dedicated permission, but an appropriate host permissionfor any patterns it passes to register().
​cookies​
cookies
Enables an extension to get and set cookies, and be notified when they change.

Permission info:
In addition to the cookies permission, this API also needs a host permissions for the sites whose cookies are to be accessed. See cookie Permissions.
​dns​
dns
Enables an extension to resolve domain names.
​downloads​
downloads,
downloads.open
Enables extensions to interact with the browser's download manager. You can use this API to save files to disk.

Permission info:
The downloads.open permission is needed to open the saved file with the systems default application.
​extension​
​
Utilities related to an extension. Gets URLs to resources packages with an extension. Gets the Window object for some of the extension's pages. Get the values for various settings.
​i18n​
​
Functions to internationalize an extension. It can be used to get localized strings from locale files packaged with an extension and to find out Thunderbird's current language.
​identity​
identity
Use the identity API to get an OAuth2 authorization code or access token, which an extension can then use to access user data from a service that supports OAuth2 access (such as Google or Facebook).
​idle​
idle
Find out when the user's system is idle, locked, or active.
​privacy​
privacy
Access and modify various privacy-related settings.
​management​
management
Gets information about installed add-ons.

Permission info:
The management permission is only needed to access information of other add-on.
​notifications​
notifications
Display notifications to the user, using the underlying operating system's notification mechanism.
​permissions​
​
Enables extensions to request extra permissions at runtime, after they have been installed.
​pkcs11​
pkcs11
Enables an extension to enumerate PKCS #11 security modules and to make them accessible as sources of keys and certificates.
​proxy​
proxy
Enables an extension to proxy web requests. Use the proxy.onRequest event listener to intercept web requests, and return an object that describes whether and how to proxy them.

Permission info:
In addition to the proxy permission, this API also needs a host permissionsfor the URLs of intercepted requests.
​runtime​
​
This module provides information about the extension and the environment it's running in. It also provides messaging APIs to:
communicate between different parts of the extension
communicate with other extensions
communicate with native applications
​storage​
storage, unlimitedStorage​
Enables extensions to store and retrieve data, and listen for changes to stored items.
​userScripts​
​
Use this API to register user scripts, third-party scripts designed to manipulate webpages or provide new features. Registering a user script instructs the browser to attach the script to pages that match the URL patterns specified during registration. In Thunderbird, user scripts can only be used in web pages loaded into tabs.

This API offers similar capabilities to contentScripts but with features suited to handling third-party scripts.
​webNavigation​
webNavigation
Add event listeners for the various stages of a navigation. A navigation consists of a frame in the browser transitioning from one URL to another, usually (but not always) in response to a user action like clicking a link.
​webRequest​
webRequest, webRequestBlocking
Add event listeners for the various stages of making an HTTP request, which includes websocket requests on ws:// and wss://. The event listener receives detailed information about the request and can modify or cancel the request.

Permission info:
In addition to the webRequest permission, this API also needs the host permission for the requested host.
To use the blocking feature, the extension must also have the webRequestBlocking API permission.
You can find more information about these APIs in the MDN WebExtension API documentation.

Supported UI Elements

Introducing Experiments

Last modified 8mo ago

API	Permission	Description
accounts	accountsRead	Enables an extension to access information of accounts and identities configured in Thunderbird's account manager.
addressBooks	addressBooks	Enables an extension to access, modify, create and delete Thunderbird address books.
browserAction		Enables an extension to interact with a browser action button. Permission info: This API does not require a permission, but a `browser_action` manifest key. Note: This API has been renamed to action in Manifest V3.
cloudFile		Enables an extension to register a cloudFile provider, which can be used to upload large attachments to a server, instead of attaching them directly to the email. Permission info: This API does not require a permission, but a `cloudFile` manifest key.
commands		The commands API adds keyboard shortcuts that can trigger actions in an extension. Permission info: This API does not require a permission, but a `commands` manifest key.
compose	compose	Enables an extension to open a new message compose window or react to events while the message is being composed.
composeAction		Enables an extension to interact with a compose action button. Permission info: This API does not require a permission, but a `compose_action` manifest key.
composeScripts	compose	Functionally is the same as the contentScripts API except that it works on the document of email messages during composition.
contacts	addressBooks	Enables an extension to access, modify, create and delete contacts in Thunderbird address books.
folders	accountsFolders	Enables an extension to access, modify, create and delete mail account folders.
mailingLists	addressBooks	Enables an extension to access, modify, create and delete mailing lists in Thunderbird address books.
mailTabs	accountsFolders	Enables an extension to interact with Thunderbird's main window. Permission info: The `accountsFolders` permission is only needed to set the currently displayed folder.
menus	menus, menus.overrideContext, accountsRead, messagesRead, activeTab	Enables an extension to add (context-) menu entries to Thunderbird menus. Permission info: The `menus.overrideContext` permission is needed to override a default menu entry. The `accountsRead` and `messagesRead` permissions are needed to populate the associated fields in the `OnClickedData` object. The `activeTab` permission is (currently) needed to get advanced information for the `onShown` event (see bug 1664423)
messageDisplay	messagesRead	Enables an extension to react on and interact with the currently displayed messages.
messageDisplayAction		Enables an extension to interact with a message display action button. Permission info: This API does not require a permission, but a `message_display_action` manifest key.
messageDisplayScripts	messagesModify	Functionally is the same as the contentScripts API except that it works on the document of email messages being displayed.
messages	messagesRead, messagesMove, accountsRead	Enables an extension to list, search, read, copy, move and delete messages. Permission info: The `messagesRead` permission is needed to list, read, mark and tag messages. The `messagesMove` permission is needed to copy, move and delete messages. The `accountsRead` permission is needed by any function/event which involves folder information.
tabs	tabs, activeTab, compose, messageModify	Enables an extension to interact with Thunderbird's tab system. It allows to create, modify, and rearrange tabs and to communicate with scripts in tabs. Permission info: The `tabs` or `activeTab` permission is only needed if the `url`, `favIconUrl` or `title` information of tabs are accessed. The `tab` permission will allow access to that information in all tabs, the `activeTab` permission restricts that to the active tab. Note: The `activeTab` permission implies the `<all_urls>` host permission for the active (web page -) tab. The `compose` permissions is needed to call `tabs.executeScript()` and `tabs.insertCSS()` for compose tabs. The `messageModify` permission is needed to call `tabs.executeScript()` and `tabs.insertCSS()` for a message display tab.
theme	theme	The theme API can be used to create static or dynamic Thunderbird themes. Theme experiments are supported. Permission info: The `theme` permission is needed to dynamically update the theme.
windows	tabs	Enables an extension to interact with Thunderbird's windows which can contain webpage tabs and also other window types like composer or address books that cannot contain webpage tabs. You can use this API to create, modify, and rearrange windows. Permission info: The `tabs` permission is needed to populate the `url`, `favIconUrl` and `title` information in the `tabs` member of the `Window` object.

API	Permission	Description
browserSettings	browserSettings	Enables an extension to modify certain global browser settings. Because these are global settings, it's possible for extensions to conflict. See the documentation for `BrowserSetting.set()` for details of how conflicts are handled.
clipboard	clipboardWrite, clipboardRead	Enables an extension to copy items to the system clipboard. Currently the API only supports copying images, but it's intended to support copying text and HTML in the future. Permission info: The `clipboardRead` permission is not used by this API but is listed here for completeness. To read from the clipboard, the Clipboard Web API has to be used and needs the `clipboardRead` permission.
contentScripts		Use this API to register content scripts to instruct the browser to insert the given content scripts into pages that match the URL patterns specified during registration. In Thunderbird, content scripts can only be used in web pages loaded into tabs. Permission info: This API does not require a dedicated permission, but an appropriate host permissionfor any patterns it passes to `register()`.
cookies	cookies	Enables an extension to get and set cookies, and be notified when they change. Permission info: In addition to the `cookies` permission, this API also needs a host permissions for the sites whose cookies are to be accessed. See cookie Permissions.
dns	dns	Enables an extension to resolve domain names.
downloads	downloads, downloads.open	Enables extensions to interact with the browser's download manager. You can use this API to save files to disk. Permission info: The downloads.open permission is needed to open the saved file with the systems default application.
extension		Utilities related to an extension. Gets URLs to resources packages with an extension. Gets the `Window` object for some of the extension's pages. Get the values for various settings.
i18n		Functions to internationalize an extension. It can be used to get localized strings from locale files packaged with an extension and to find out Thunderbird's current language.
identity	identity	Use the identity API to get an OAuth2 authorization code or access token, which an extension can then use to access user data from a service that supports OAuth2 access (such as Google or Facebook).
idle	idle	Find out when the user's system is idle, locked, or active.
privacy	privacy	Access and modify various privacy-related settings.
management	management	Gets information about installed add-ons. Permission info: The `management` permission is only needed to access information of other add-on.
notifications	notifications	Display notifications to the user, using the underlying operating system's notification mechanism.
permissions		Enables extensions to request extra permissions at runtime, after they have been installed.
pkcs11	pkcs11	Enables an extension to enumerate PKCS #11 security modules and to make them accessible as sources of keys and certificates.
proxy	proxy	Enables an extension to proxy web requests. Use the `proxy.onRequest` event listener to intercept web requests, and return an object that describes whether and how to proxy them. Permission info: In addition to the `proxy` permission, this API also needs a host permissionsfor the URLs of intercepted requests.
runtime		This module provides information about the extension and the environment it's running in. It also provides messaging APIs to: communicate between different parts of the extension communicate with other extensions communicate with native applications
storage	storage, unlimitedStorage	Enables extensions to store and retrieve data, and listen for changes to stored items.
userScripts		Use this API to register user scripts, third-party scripts designed to manipulate webpages or provide new features. Registering a user script instructs the browser to attach the script to pages that match the URL patterns specified during registration. In Thunderbird, user scripts can only be used in web pages loaded into tabs. This API offers similar capabilities to contentScripts but with features suited to handling third-party scripts.
webNavigation	webNavigation	Add event listeners for the various stages of a navigation. A navigation consists of a frame in the browser transitioning from one URL to another, usually (but not always) in response to a user action like clicking a link.
webRequest	webRequest, webRequestBlocking	Add event listeners for the various stages of making an HTTP request, which includes websocket requests on `ws://` and `wss://`. The event listener receives detailed information about the request and can modify or cancel the request. Permission info: In addition to the `webRequest` permission, this API also needs the host permission for the requested host. To use the blocking feature, the extension must also have the `webRequestBlocking` API permission.