WebExtension API Documentation & Guides (Thunderbird 152, Manifest V3)

These documents assume you already have some familiarity with the WebExtension technology. If not, it is highly recommended to start with the following pages:

For any problems or feature requests please file a bug.

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.

The documentation for the APIs listed in the left side panel is generated automatically from Thunderbird’s schema files. The webext-schemas repository can be used to obtain a copy of the relevant files.

Guides Overview

Vendoring 3rd party libraries: Learn how to bundle third-party libraries into your add-on and declare them so reviewers can verify the sources are unmodified and automated tooling can audit them for known vulnerabilities. This guide covers the trusted source requirements and both accepted declaration formats: a VENDOR.md file and a version-pinned package.json.
Strategies to avoid using innerHTML: Understand why innerHTML is discouraged in Thunderbird WebExtensions and which safer patterns to use instead. This guide covers alternatives such as textContent, createElement(), templates, and CSS show/hide, replacing inline event handlers with real listeners, and safely rendering external or user-provided markup with the built-in Sanitizer API through Element.setHTML() (Thunderbird 148 and later).
Working with WebExtension events: Attach listeners to Thunderbird WebExtension events with addListener(). This guide shows how to register both named and anonymous listener functions, how to read the parameters an event passes to its listener, and how to use the extra addListener() arguments that some events accept, such as monitorAllFolders on messages.onNewMailReceived.
Using runtime messages: See how different parts of a Thunderbird WebExtension communicate using runtime messages. This guide explains how to register runtime.onMessage listeners and send messages between scripts, common quirks to be aware of, and how multiple listeners coordinate their responses.
Working with message lists: Discover how to efficiently work with large mail folders in Thunderbird WebExtensions. This guide explains how message lists are paginated so a single query does not load thousands of messages at once, how to walk through the pages returned by the API, and how to iterate over messages with generators. It also covers running asynchronous queries, handling auto-pagination, and safely aborting an ongoing query to keep performance and memory use under control.
Working with vCard contacts: Explore how to manage Thunderbird contacts, which are stored as vCards and exposed through the vCard property. This guide recommends parsing and editing them with the same ical.js library Thunderbird itself uses, shows how to bundle it and import it from a module background script, and how to read and update individual vCard fields safely. It also points to Vendoring 3rd party libraries for declaring the bundled library.
Converting extensions to Manifest V3: Migrate a Thunderbird WebExtension from Manifest V2 to Manifest V3, officially supported since Thunderbird 128 ESR. This guide documents the backward-incompatible API changes the add-on team made on top of the general Firefox migration, grouped by API, covering changed default values, removed or replaced functions, and adjusted types. It also points to the converted sample extensions for reference.

Where to get help and more information

Introduction to add-on development: Find information about creating and updating extensions for Thunderbird. Includes getting-started-tutorials and a collection of helpful articles and guides.
Add-on developer community: Learn how to get in touch with other Thunderbird add-on developers, to ask questions and to share knowledge.
Example extensions: A collection of WebExtensions, showing how to use Thunderbird WebExtension APIs.
MDN sample extensions: A collection of WebExtensions, showing how to use WebExtension APIs in Firefox. 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.