Thunderbird Teams Provider

A Thunderbird extension that integrates Microsoft Teams chat directly into Thunderbird.

Features

• Unified inbox experience – access all your Teams chats without leaving Thunderbird.
• Chat list – all your Teams conversations listed in the left panel, grouped and sorted by recent activity.
• Message view – full conversation thread displayed on the right when a chat is selected.
• Send messages – type a reply in the compose field at the bottom and press Enter to send.
• Unread indicators – chats with new messages are shown in bold (Thunderbird style), with a badge count on the Teams button.
• Avatar or initials – profile photos are shown by default; an option lets you disable them and show sender initials (first + last name) in a coloured circle instead.
• Automatic refresh – chats and messages are polled every 30 seconds; the current open thread refreshes every 15 seconds.

---

Table of Contents

1. Building on Linux
2. Allowing the plugin to access your Teams account
3. Plugin options
4. Installing on Thunderbird
   • Standard installation (DEB / RPM / tarball)
   • Snap installation
5. Development workflow
6. CI / CD

---

Building on Linux

Prerequisites

Dependency	Minimum version	Install
Node.js	18	sudo apt install nodejs or nvm
npm	8	bundled with Node.js
git	any	sudo apt install git

Ubuntu / Debian one-liner:

sudo apt update && sudo apt install -y nodejs npm git

Fedora / RHEL:

sudo dnf install -y nodejs npm git

Build steps

# 1 – Clone the repository
git clone https://github.com/gortazar/thunderbird-teams-provider.git
cd thunderbird-teams-provider

# 2 – Install build tools (web-ext)
npm install

# 3 – Lint the extension (optional but recommended)
npm run lint

# 4 – Build the .xpi file
npm run build

The build output is placed in web-ext-artifacts/thunderbird_teams_provider-<version>.xpi.

---

Allowing the plugin to access your Teams account

Quick answer — do end-users need any Azure setup?

No. If you download an already-built .xpi from the Releases page, you just install it and click Sign in with Microsoft. No Azure portal, no Client ID, no configuration of any kind. The experience is identical to adding a Microsoft email account in Thunderbird.

TL;DR for end-users:

1. Install the .xpi from Releases.
2. Click the Teams button in the Thunderbird sidebar.
3. Click Sign in with Microsoft → enter your email, password, one-time code.
4. On first sign-in your organisation may ask you to approve the app once (same one-time screen you saw when adding your Microsoft email to Thunderbird).
5. Done — your chats load automatically.

---

For the extension publisher — one-time app registration (required before distributing)

This section is for whoever builds and publishes the .xpi, not for end-users. If you are just installing a pre-built release you can skip everything below.

The extension ships with a placeholder Client ID in the source code:

const DEFAULT_CLIENT_ID = "YOUR_EXTENSION_CLIENT_ID_HERE";

Before you publish a build you must replace this placeholder with a real Azure AD Application (client) ID. You only need to do this once, and you do not need your organisation's Azure account — a free personal Microsoft account (e.g. outlook.com, hotmail.com) is enough to register a multi-tenant application that any work or school account can sign in to.

Step 1 – Register an Azure AD application

1. Sign in to the Azure portal with any Microsoft account (personal accounts work fine).
2. Navigate to Azure Active Directory → App registrations → New registration.
3. Fill in the form:
   • Name: Thunderbird Teams Provider (or any name you prefer)
   • Supported account types: Accounts in any organizational directory and personal Microsoft accounts — this allows users from any organisation to sign in.
   • Redirect URI: select Public client / native (mobile & desktop) and enter the redirect URL shown in the extension options page (see below).
4. Click Register.

Step 2 – Add API permissions

1. Go to API permissions → Add a permission → Microsoft Graph → Delegated permissions.
2. Add: Chat.ReadWrite, User.Read, offline_access.
3. Click Add permissions.

Chat.ReadWrite is a user-delegated permission. Users consent to it themselves on first sign-in. No admin pre-approval is needed for most tenants.

Step 3 – Embed the Client ID and build

Replace the placeholder in background/background.js:

const DEFAULT_CLIENT_ID = "YOUR_EXTENSION_CLIENT_ID_HERE";

with your Application (client) ID from the Azure portal overview page, then build:

npm run build

The generated .xpi in web-ext-artifacts/ is ready to distribute. Users of your build just install it and click Sign in — no further configuration required.

---

For organisation administrators — admin consent (optional)

Some organisations configure Azure AD to require an administrator to pre-approve any app before users can sign in to it. If your users see a "Need admin approval" screen, an Azure AD global administrator can grant tenant-wide consent via:

https://login.microsoftonline.com/<TENANT_ID>/adminconsent?client_id=<CLIENT_ID>

Replace <TENANT_ID> with your Directory (tenant) ID and <CLIENT_ID> with the extension's Application ID. After this one-time approval, users sign in normally.

---

Plugin options

Open Thunderbird → Add-ons Manager → Thunderbird Teams Provider → Preferences (or click Open Options on the sign-in screen).

Option	Description
Client ID (advanced)	Override the extension's built-in Azure AD app ID. Leave blank to use the pre-configured default.
Tenant ID (advanced)	Override the Azure AD tenant. Leave blank for common (personal and work accounts).
Disable avatars	When checked, profile photos are never fetched. Each sender is represented by a coloured circle containing their initials (first letter of first name + first letter of last name, e.g. JS for Jane Smith). Useful for privacy or bandwidth savings.
Sign in / Sign out	Authenticate or revoke the session. Tokens are stored locally in Thunderbird's secure extension storage.

---

Installing on Thunderbird

Download the latest .xpi file from the Releases page.

Standard installation

Works for Thunderbird installed via DEB package, RPM, tarball, or Flatpak.

Method A – Drag and drop

Drag the .xpi file onto the Thunderbird window. Thunderbird will prompt you to install it.

Method B – Add-ons Manager

1. Open Thunderbird.
2. Press Ctrl+Shift+A to open the Add-ons Manager.
3. Click the ⚙ gear icon (top-right of the add-ons list).
4. Select Install Add-on From File….
5. Browse to the downloaded .xpi and click Open.
6. Click Add on the confirmation prompt.

After installation a Teams button (purple T icon) appears in the vertical spaces toolbar on the left side of the Thunderbird window.

Snap installation

The official Thunderbird snap (thunderbird from Canonical) runs in a confined sandbox. Extensions are installed the same way as for the standard package:

1. Open the Thunderbird snap application.
2. Press Ctrl+Shift+A → gear icon → Install Add-on From File….
3. Select the .xpi file.

Note: The snap's sandbox does not restrict Thunderbird's ability to load extensions via the Add-ons Manager. You do not need to run any snap connect commands for this extension.

Tip: If the file picker in the snap cannot see your Downloads folder, copy the .xpi to your home directory first:

cp ~/Downloads/thunderbird_teams_provider-*.xpi ~/

Then browse to ~ in the file picker.

---

Development workflow

# Run the extension inside Thunderbird (hot-reload)
npm run start

This launches a temporary Thunderbird profile with the extension pre-loaded. You need Thunderbird installed and on $PATH (or set WEB_EXT_FIREFOX to the Thunderbird binary path).

# Lint without building
npm run lint

---

CI / CD

The GitHub Actions workflow (.github/workflows/build.yml) runs on every pull request and every push to main:

1. Lint – web-ext lint checks the extension for common issues.
2. Build – web-ext build produces a signed-ready .xpi.
3. Artifact – the .xpi is uploaded as a workflow artifact (available for 30 days).
4. Release – on a successful push to main a GitHub Release is automatically created and the .xpi is attached as the release asset.

---

License

Apache 2.0 – see LICENSE.