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.
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.
legacy This API enables Thunderbird “legacy” extensions to continue working in the WebExtensions world.
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.
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.

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.