A Guide to MailExtensions

Search…
How to build MailExtensions for Thunderbird.
Introduction
MailExtensions are based on the WebExtension technology, which is also used by many web browsers. Such an extension is a simple collection of files which modify Thunderbirds appearance and behavior. It can add user interface elements, alter content, or perform background tasks. MailExtensions are created using standard JavaScript, CSS and HTML. Interaction with Thunderbird itself, like adding UI elements or accessing the users messages or contacts is done through special WebExtension APIs.
Even though Thunderbird Themes are also MailExtensions, they have a very distinct objective and are therefore described in their own guide.
Unlike older legacy extensions, MailExtensions access functionality through stable WebExtension APIs and do not have direct access to Thunderbird's internal components or UI elements. Consequently, MailExtensions are less likely to break and do not need frequent and complex updates when Thunderbird's internals change.
The main configuration file of a MailExtension is a file called manifest.json, also referred to as the manifest. Besides defining some of the extension's basic properties like name, description and ID, it also defines how the extension hooks into Thunderbird:
manifest.json
1
{
2
    "manifest_version": 2,
3
    "name": "Hello World",
4
    "description": "A basic Hello World extension!",
5
    "version": "1.0",
6
    "author": "[Your Name Here]",
7
    "applications": {
8
        "gecko": {
9
            "id": "[email protected]",
10
            "strict_min_version": "78.0",
11
            "strict_max_version": "78.*"
12
        }
13
    },
14
    "icons": {
15
        "64": "images/icon-64px.png",
16
        "32": "images/icon-32px.png",
17
        "16": "images/icon-16px.png"
18
    },
19
    "background": {
20
        "scripts": [
21
            "background.js"
22
        ]
23
    },
24
    "options_ui": {
25
      "page": "options/options.html",
26
      "open_in_tab": false,
27
      "browser_style": true
28
    },
29
    "permissions": [
30
      "storage"
31
    ]
32
}
Copied!
Manifest keys
A list of all manifest keys supported by Thunderbird can be found in the following document:
Supported Manifest Keys
The most commonly used manifest keys are explained below.
Basic extension properties
The following manifest keys define basic properties:
manifest_version: mandatory key to signal compatibility to Thunderbird, must be set to 2
name : mandatory key to set the name of the extension
version : mandatory key to define a number that denotes the version of the extension
description : a brief description of what the extension does
author : should be the name of a person or company representing the extensions developer
The name and the description of the given example are only in English. This MDN article about Localization explains how to use the WebExtension i18n API to localize these keys.
The applications.gecko manifest key defines the following properties:
id: The id serves as a unique identifier for the extension and is mandatory in order upload an extension to ATN or to be able to install it from an XPI file.

Best practice is to use an "email-address-style" id (but not a real email address) on a domain you control, for example [email protected], if you own example.com. As the id of your add-on cannot be changed once it is published, it is highly recommended to use a domain that you plan to keep for the forseeable future. If you don't have a domain that fits the bill, feel free to use your-atn-username.addons.thunderbird.net (based on your username on ATN).

Alternatively to the preferred style, you may use an UUID enclosed in curly braces, for example
{e4aa2097-8ee9-49a4-9ec7-c633b1e8dfda}. Make sure you generate a new UUID for each add-on you want to develop, you can find free UUID generators throughout the internet.
strict_min_version: Defines the lowest targeted version of Thunderbird.
strict_max_version: Defines the highest targeted version of Thunderbird. It can be set to a specific version or a broader match to limit it to a branch (for example 78.*).
1
    "applications": {
2
        "gecko": {
3
            "id": "[email protected]",
4
            "strict_min_version": "78.0",
5
            "strict_max_version": "78.*"
6
        }
7
    }
Copied!
Extension Icons
The icons manifest key tells Thunderbird the location of icons, which should be used to represent the MailExtension. Thunderbird supports basic image types like PNG files, but also SVG files. Thunderbird uses different file icon sizes in different places and allows registering a dedicated file for each size. The MailExtension will use the standard puzzle icon, if no icons have been defined.
1
    "icons": {
2
        "64": "images/icon-64px.png",
3
        "32": "images/icon-32px.png",
4
        "16": "images/icon-16px.png"
5
    }
Copied!
Background Page
Each MailExtension has a hidden background page. Its main purpose is to load and execute JavaScript files when the MailExtension is loaded. There are two options for its definition:
Defining one or more background scripts
1
    "background": {
2
        "scripts": [
3
            "common.js",
4
            "background.js"
5
        ]
6
    }
Copied!
This will create the background page on-the-fly and load the provided scripts. This is identical to the following background page definition.
Defining a background page
1
    "background": {
2
        "page": "background.html"
3
    }
Copied!
The defined background page can then load the JavaScript files:
1
<html lang="en">
2
    <head>
3
        <meta charset="utf-8">
4
        <script src="common.js"></script>
5
        <script src="background.js"></script>
6
    </head>
7
    <body>
8
    </body>
9
</html>
Copied!
Options Page
The options_ui manifest key defines the standard MailExtension options page. The defined page will be displayed in the add-on manager.
1
    "options_ui": {
2
      "page": "options/options.html",
3
      "open_in_tab": false,
4
      "browser_style": true
5
    }
Copied!
The appearance of the options page can be configured as follows:
open_in_tab : Open the options page in a tab instead of inline in the add-ons property page.
browser_style: Use default browser styles for the options page (recommended).
An inline options page may look as follows:
User Interface Elements
Some UI elements MailExtensions can use are controlled by manifest keys, for example
browser_action
compose_action
message_display_action
Further information about these UI elements can be found in the following document:
Supported UI Elements
Permissions
A core principle of the WebExtension technology is the use of permissions, so users can see which areas of Thunderbird a MailExtension wants to access. Add-on developers can predefine all requested permissions in the permissions manifest key:
1
    "permissions": [
2
      "storage"
3
    ]
Copied!
As permissions allow WebExtensions to use certain APIs, information about supported permissions can be found in the following document:
Supported WebExtension APIs
The user may not deny individual permissions requested in the permissions manifest key. He must either accept all of them during add-on install, or abort the install. It is however possible to request optional permissions, which can be managed by the user during runtime.
WebExtension Scripts
Most entry points defined in the extensions manifest allow adding scripts. Most prominent of course the background script(s). Furthermore, each defined HTML page, like the options_ui page allow including scripts via standard HTML <script> tags.
In order to use modern ES6 modules in a loaded script, the type attribute of its script tag must be set to module.
1
<script type="module" src="background.js"></script>
Copied!
All these WebExtension scripts have access to:
Standard JavaScript methods
​Web API (if the browser compatibility chart lists Firefox, the API also works in Thunderbird)
WebExtension API
A list of all WebExtension APIs supported by Thunderbird can be found in the following document:
Supported WebExtension APIs
Content Scripts
Content scripts (including compose scripts and message display scripts) can only access a small subset of the WebExtension APIs, but they can communicate with background scripts using a messaging system, and thereby indirectly access the WebExtension APIs.
Option Scripts
Access to WebExtension APIs in options pages using options_ui.open_in_tab: false is currently broken. Use getBackgroundPage() to replace the browser object of the options page with the browser object of your background page.
1
const browser = window.browser.extension.getBackgroundPage().browser;
Copied!
CloudFile Management Scripts
A script loaded from a CloudFile management_url has access to a limited subset of the WebExtension APIs:
cloudFile
extension
i18n
runtime
storage
Creating MailExtensions: Examples
Our sample-extensions repository includes a few simple MailExtensions, which showcase different APIs and which will get you started to create your own extension.
We also prepared a step-by-step guide for a small Hello World MailExtension:
Hello World Extension Tutorial
Experiment APIs
The currently available WebExtension APIs are not yet sufficient, as some areas of Thunderbird are not accessible through these APIs. We are working on improving the situation.
Currently and for the foreseeable future Thunderbird supports Experiment APIs (a.k.a. Experiments), which are WebExtension APIs that are bundled and shipped together with a MailExtension. They interact directly with Thunderbird's internal APIs and allow add-ons to use additional features not yet available via built-in WebExtension APIs.
These additional APIs can be registered in the manifest.json file by defining an implementation script and a schema file describing the interface:
1
    "experiment_apis": {
2
        "LegacyPrefs": {
3
            "schema": "api/LegacyPrefs/schema.json",
4
            "parent": {
5
                "scopes": ["addon_parent"],
6
                "paths": [["LegacyPrefs"]],
7
                "script": "api/LegacyPrefs/implementation.js",
8
                "events": ["startup"]
9
            }
10
        }
11
    }
Copied!
Experiment APIs have full access to Thunderbird's core functions and can bypass the WebExtension permission system entirely. Including one or more Experiment APIs will therefore disable the individual permission prompt and instead prompt the user only for the Have full, unrestricted access to Thunderbird, and your computer permission.
The use of optional permissions is not supported for the same reason.
If you'd like to learn more about experiments, check out this detailed introduction:
Introducing Experiments
Sharing Experiment APIs
Developers can share and re-use Experiments, if their add-ons have similar needs. Before starting to work on your own Experiment, check if any of the following APIs could already provide the functionality you need. Using them and providing feedback to their developers will help to improve these APIs.
Name
Text
Description
​CachingFix​
​
Adding this Experiment API will automatically fix caching issues when the add-on is updated, disabled or uninstalled.
​Calendar​
​💬 📝​
Draft for calendar-related APIs in Thunderbird.
​ComposeMessageHeaders​
​
Adds missing functionality to add headers to a newly composed message. Aims to add a header object to the compose.ComposeDetails object, so headers can be set via compose.setComposeDetails.
​CustomUI​
​💬​
A generic UI extension framework based on iframes registered at fixed extension points.
​FileSystem​
​
An API to access files in the users profile folder. Until Mozilla has made a final decision about including the Chrome FileSystem API, this API can be used as an interim solution.
​LegacyMenu​
​
Add menu entries to Thunderbird menus currently not accessible using the built-in menus API.
​LegacyPrefs​
​
Access Thunderbird system preferences.
​NotificationBar​
​💬 📝​
Add Thunderbird notification bars.
​NotifyTools​
​
Provides a messaging system between legacy code and the WebExtension background.
​onAfterSend​
​
Adds "onAfterSend" event. It returns the messageId of the sent email in the Sent folder.
​ResourceUrl​
​
Register a custom resource:// URL to be able to load custom JSM files.
​Runtime.onDisable​
​
Permit WebExtensions to perform (time-limited) cleanup tasks after the add-on is disabled or uninstalled.
​TagService​
​B 💬​
Add/Manage email tags.
​TCP​
​
TCP support based on ArrayBuffers (currently client side only).
💬: API has a public announcement post
📝: API has a public interface discussion
B : Bugzilla Bug
If you have created an Experiment API which you think could be beneficial to other developers, please tell us about it, so we can include it here.
Proposing APIs to be included in Thunderbird
Creating a good WebExtension API for Thunderbird is not an easy task. New APIs need to be generic and distinct from other APIs. Their interfaces have to be designed with foresight as we should avoid scenarios, where we have to make backward incompatible changes later because we have missed something.
If you want to propose and maybe collaborate on a new API, the following process is suggested:
1.Announcing the idea and a first outline of the suggested API on discuss.thunderbird.net. An actual implementation is not yet needed, but a general concept of how the API is supposed to work is helpful. This allows the add-on developer community to provide feedback and to make sure the design will cover their needs as well.
2.Publishing a detailed API description, which can be viewed and commented. Google docs have worked quite well (see here and here), but any platform that allows to collaborate will be sufficient. The goal is to shape out the event, function and type definitions of the API.
3.Creating a tracking bug on bugzilla, referencing the API description, so the core development team is notified and can comment as well.
4.Publishing a working implementation, so add-on developers can use it and provide feedback.
5.Adding a patch to the tracking bug and request review.