Thunderbird WebExtension API Documentation

These documents assume you already have some familiarity with the WebExtension technology. If not, it is highly recommended to read our Guide to MailExtensions or some of the MDN documentation on the subject.

Hint

In Thunderbird, all WebExtension API can be accessed through the browser.* namespace, as with Firefox, but also through the messenger.* namespace, which is a better fit for Thunderbird.

Important

WebExtension APIs are asynchronous, that is, they return a Promise object which resolves when ready. See Using Promises for more information about Promises.

This documentation includes the following topics:

For any problems or feature requests please file a bug.

Thunderbird WebExtension APIs

Thunderbird provides the following messenger related WebExtension APIs, which are sometimes referred to as MailExtension APIs:

Thunderbird API

Description

accounts

Enables an extension to access information of accounts and identities configured in Thunderbird’s account manager.

addressBooks

Enables an extension to access, modify, create and delete Thunderbird address books.

browserAction

Enables an extension to interact with a browser action button.

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.

commands

The commands API adds keyboard shortcuts that can trigger actions in an extension.

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.

composeScripts

Functionally is the same as the contentScripts API except that it works on the document of email messages during composition.

contacts

Enables an extension to access, modify, create and delete contacts in Thunderbird address books.

folders

Enables an extension to access, modify, create and delete mail account folders.

mailingLists

Enables an extension to access, modify, create and delete mailing lists in Thunderbird address books.

mailTabs

Enables an extension to interact with Thunderbird’s main window.

menus

Enables an extension to add (context-) menu entries to Thunderbird menus.

messageDisplay

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.

messageDisplayScripts

Functionally is the same as the contentScripts API except that it works on the document of email messages being displayed.

messages

Enables an extension to list, search, read, copy, move and delete messages.

tabs

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.

windows

Enables an extension to interact with Thunderbird’s windows which can contain webpage tabs and also with other window types like composer or address books that cannot contain webpage tabs. You can use this API to create, modify, and rearrange windows.

The documentation for these APIs is generated automatically from the schema documents at mail/components/extensions/schemas.

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.

Note

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.

Firefox API

Description

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

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.

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.

cookies

Enables an extension to get and set cookies, and be notified when they change.

dns

Enables an extension to resolve domain names.

downloads

Enables extensions to save files to disk.

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

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).

Added in Thunderbird 78.0b2

idle

Find out when the user’s system is idle, locked, or active.

privacy

Access and modify various privacy-related settings.

management

Gets information about installed add-ons.

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.

protocol_handlers

Using this manifest key will register one or more web-based protocol handlers. It allows to register a website or an extension page as a handler for a particular protocol.

pkcs11

Enables an extension to enumerate PKCS #11 security modules and to make them accessible as sources of keys and certificates.

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.

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 and communicate with native applications.

storage

Enables extensions to store and retrieve data, and listen for changes to stored items.

theme

Enables extensions to update the theme, thus creating a dynamic theme.

theme_experiment

Using this manifest key enables the definition of experimental theme key properties for the Thunderbird interface. These experiments are a precursor to proposing new theme features for inclusion in Thunderbird.

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

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

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.

Where To Get Help And More Information

Thunderbird add-on developer documentation

Find information about creating and updating extensions for Thunderbird. Includes getting-started-tutorials and a collection of helpful articles and guides.

Thunderbird add-on developer community

Learn how to get in touch with other add-on developers, to ask questions and to share knowledge.

Thunderbird sample extensions

A collection of MailExtensions, showing how to use Thunderbird WebExtension APIs.

MDN sample extensions

A collection of WebExtensions, showing how to use WebExtension APIs. They probably won’t work directly in Thunderbird, but they may provide hints on how to use some of the WebExtension APIs that Thunderbird inherited from Firefox.

MDN WebExtension documentation

Find general information about the WebExtensions API cross-browser technology used by Firefox and many Chromium-based browsers. Not all information listed there apply to Thunderbird.