Thunderbird-Add-on entwickeln mit MailExtensions

Ein Thunderbird-Add-on entsteht heute als MailExtension. Das Format folgt dem WebExtensions-Modell von Firefox: eine manifest.json, ein Hintergrundskript, optionale HTML-Oberflächen und JavaScript. Dazu kommen Schnittstellen, die es nur im E-Mail-Programm gibt, etwa für Nachrichten, Ordner, Konten, Adressbücher und das Verfassen. Wer schon eine Browser-Erweiterung gebaut hat, findet sich sofort zurecht.

Was eine MailExtension ausmacht

Das Grundgerüst kennen Sie aus dem Browser. Wie Hintergrundskript, Popup und Optionsseite zusammenspielen, erklärt der Artikel Content Scripts, Service Worker, Popup. In Thunderbird verschieben sich die Schwerpunkte:

Schritt 1: Das Manifest

{
  "manifest_version": 2,
  "name": "Neue-Mail-Zähler",
  "version": "1.0.0",
  "description": "Zeigt an, wie viele neue Nachrichten seit dem Start eingetroffen sind.",
  "browser_specific_settings": {
    "gecko": {
      "id": "neue-mail-zaehler@beispiel.de",
      "strict_min_version": "128.0"
    }
  },
  "background": {
    "scripts": ["background.js"]
  },
  "browser_action": {
    "default_title": "Neue Mails",
    "default_icon": "icons/icon-32.png"
  },
  "permissions": ["messagesRead", "accountsRead"]
}

Die ID unter browser_specific_settings ist Pflicht und identifiziert das Add-on dauerhaft. Mit strict_min_version legen Sie fest, ab welcher Thunderbird-Version es laufen soll. Wählen Sie hier eine aktuelle Version mit erweitertem Support (ESR), die Sie selbst getestet haben.

Thunderbird unterstützt Manifest V2 und, in neueren Versionen, auch Manifest V3. Bei V3 heißt die Schaltfläche action statt browser_action, und einige Schnittstellen verhalten sich anders. Für den Einstieg ist V2 in Thunderbird weiterhin ein gangbarer Weg; prüfen Sie für neue Projekte in der Dokumentation, welche Version empfohlen wird. Die Unterschiede der Manifest-Versionen im Browser beschreibt der Artikel zum Firefox-Add-on.

Schritt 2: Das Hintergrundskript

// background.js
let zaehler = 0;

messenger.messages.onNewMailReceived.addListener((ordner, nachrichtenliste) => {
  zaehler += nachrichtenliste.messages.length;
  messenger.browserAction.setBadgeText({ text: String(zaehler) });
});

messenger.browserAction.onClicked.addListener(() => {
  zaehler = 0;
  messenger.browserAction.setBadgeText({ text: "" });
});

Das Skript hört auf eingehende Nachrichten und zeigt die Anzahl als kleines Abzeichen an der Schaltfläche. Ein Klick setzt den Zähler zurück. Ereignisse wie onNewMailReceived sind das typische Muster: Das Add-on reagiert auf das, was im E-Mail-Programm passiert, statt ständig nachzufragen.

Die wichtigsten Schnittstellen

• messages: Nachrichten auflisten, abfragen, ganze Inhalte lesen (getFull), markieren, verschieben, Schlagwörter setzen.
• folders und accounts: Konten und Ordnerstruktur lesen, Ordner anlegen oder umbenennen.
• messageDisplay: erfährt, welche Nachricht gerade angezeigt wird. Dazu passt die Schaltfläche messageDisplayAction in der Kopfzeile einer Nachricht.
• compose: Verfassen-Fenster öffnen, Empfänger, Betreff und Text lesen oder setzen. Mit onBeforeSend lässt sich vor dem Versand prüfen, etwa ob ein angekündigter Anhang fehlt. Die Schaltfläche heißt hier composeAction.
• addressBooks und contacts: Adressbücher und Kontakte lesen und bearbeiten.
• menus: eigene Einträge in Kontextmenüs, etwa beim Rechtsklick auf eine Nachricht.
• storage: Einstellungen und Daten des Add-ons speichern, wie im Browser.

Viele Listen liefert Thunderbird seitenweise. Wer alle Nachrichten eines Ordners braucht, folgt der Paginierung, statt nur die erste Seite auszuwerten.

Beispiel: Prüfung vor dem Versand

messenger.compose.onBeforeSend.addListener(async (tab, details) => {
  const text = (details.plainTextBody || details.body || "").toLowerCase();
  const anhaenge = await messenger.compose.listAttachments(tab.id);
  if (text.includes("im anhang") && anhaenge.length === 0) {
    return { cancel: true };
  }
});

Erwähnt der Text einen Anhang, ist aber keiner dabei, wird der Versand abgebrochen. Dafür braucht das Add-on die Berechtigung compose. In einer echten Erweiterung würden Sie die Person zusätzlich mit einem Hinweis informieren, statt den Versand stumm zu stoppen.

Berechtigungen

MailExtensions greifen auf sehr persönliche Daten zu. Thunderbird zeigt deshalb bei der Installation an, welche Rechte ein Add-on anfordert. Typische Berechtigungen sind messagesRead zum Lesen, messagesModify zum Markieren und Verändern, messagesMove zum Verschieben, accountsRead für Konten und Ordner sowie compose für das Verfassen. Fordern Sie nur an, was die Funktion wirklich braucht. Ein Add-on, das nur Schlagwörter setzt, braucht keinen Zugriff auf Adressbücher. Wer weniger verlangt, wird eher installiert und kommt leichter durch die Prüfung.

Optionsseite und Übersetzungen

Fast jedes Add-on braucht ein paar Einstellungen. Wie im Browser legen Sie dafür im Manifest eine Optionsseite an, eine gewöhnliche HTML-Datei, die in der Add-on-Verwaltung von Thunderbird erscheint:

"options_ui": {
  "page": "options.html"
}

Die Werte speichern Sie mit messenger.storage.local.set() und lesen sie im Hintergrundskript mit messenger.storage.local.get(). Über messenger.storage.onChanged erfährt das Hintergrundskript, wenn sich eine Einstellung geändert hat, und muss nicht neu gestartet werden.

Für mehrsprachige Add-ons legen Sie einen Ordner _locales mit Unterordnern wie de und en an, jeweils mit einer Datei messages.json. Im Manifest verweisen Sie mit Platzhaltern wie __MSG_extensionName__ auf diese Texte, im Code mit messenger.i18n.getMessage(). Thunderbird wählt dann automatisch die Sprache der Oberfläche. Das ist besonders bei Add-ons sinnvoll, die über addons.thunderbird.net international verbreitet werden sollen.

Schritt 3: Laden und debuggen

1. In Thunderbird den Add-on-Debugger öffnen: über das Menü der Entwicklerwerkzeuge oder über die Add-on-Verwaltung und das Zahnradmenü.
2. Die Option zum temporären Laden wählen und die manifest.json Ihres Projekts auswählen.
3. Über „Untersuchen“ öffnen Sie die Konsole des Hintergrundskripts. Fehler und Ausgaben von console.log erscheinen dort.
4. Nach Änderungen laden Sie das Add-on mit „Neu laden“ neu, ohne Thunderbird zu beenden.

Ein temporär geladenes Add-on verschwindet beim Neustart wieder. Testen Sie am besten in einem eigenen Thunderbird-Profil mit einem Testkonto, damit ein Fehler nicht Ihre echten Nachrichten verschiebt oder verändert.

Typische Fehler

• Berechtigung vergessen: Ruft das Add-on eine Schnittstelle ohne passende Berechtigung auf, ist das Objekt oft gar nicht vorhanden. Die Konsole zeigt dann einen Fehler wie „undefined“ statt einer klaren Meldung.
• Nur die erste Seite gelesen: Listen von Nachrichten kommen seitenweise. Wer nur die erste Seite auswertet, übersieht in großen Ordnern einen Teil der Nachrichten.
• Zustand nur im Speicher: Variablen im Hintergrundskript gehen verloren, wenn es neu startet. Wichtige Werte gehören in storage.local.
• Zu alte Mindestversion: Eine Schnittstelle, die erst in neueren Versionen existiert, fehlt bei Nutzern mit älterem Thunderbird. Passen Sie strict_min_version an oder prüfen Sie im Code, ob die Funktion vorhanden ist.

Experiments: wenn die Schnittstellen nicht reichen

Manche Funktionen sind über die offiziellen Schnittstellen nicht erreichbar. Für diese Fälle erlaubt Thunderbird sogenannte Experiments: Erweiterungen der API, die auf Programminterna zugreifen. Sie sind mächtig, aber riskant. Weil sie an internen Code gebunden sind, können sie mit jedem größeren Update brechen, und sie werden bei der Veröffentlichung gründlicher geprüft. Nutzen Sie Experiments nur, wenn es keinen anderen Weg gibt, und prüfen Sie regelmäßig, ob die benötigte Funktion inzwischen als offizielle Schnittstelle verfügbar ist.

Veröffentlichen auf addons.thunderbird.net

Für die Verteilung packen Sie die Dateien des Add-ons als ZIP-Archiv, wobei die manifest.json im Hauptverzeichnis des Archivs liegen muss. Auf addons.thunderbird.net (ATN) legen Sie ein Entwicklerkonto an, laden das Archiv hoch und ergänzen Beschreibung, Screenshots und Lizenz. Neue Einreichungen werden geprüft, bevor sie öffentlich erscheinen. Geben Sie in der Beschreibung genau an, welche Thunderbird-Versionen Sie getestet haben und wofür jede Berechtigung gebraucht wird.

Alternativ lässt sich ein Add-on auch selbst als Datei verteilen, etwa im Unternehmen. Hinweise zu Store-Einträgen, Prüfungen und Beschreibungstexten finden Sie im Bereich Add-ons veröffentlichen.