TabMail for Thunderbird

An open-source AI email assistant for Thunderbird. Tap, Talk, Send.

Auto replies, email triage, conversational editing, and chat with your inbox. Autocomplete helps you finish the thought. Search your email locally and work with your calendar from the same assistant.

See it in action

tabmail-promo-tb.mp4

Can't see the video? Watch it on YouTube.

Get TabMail

This add-on targets Thunderbird 145+ and Manifest V3, with Experiment APIs for Thunderbird-specific integration.

---

Architecture (high level)

Thunderbird (local mail + calendars)
  ├─ chat/        (UI + tool orchestration + FSM workflows)
  ├─ agent/       (message workflows, tagging, summarization, reminders)
  ├─ compose/     (autocomplete + editing UX)
  ├─ fts/         (local search index + memory; native host required)
  ├─ theme/       (palette-based theming + UI tweaks)
  ├─ config/      (options UI)
  ├─ prompts/     (custom user prompts)
  ├─ templates/   (email templates)
  ├─ marketplace/ (community template marketplace)
  ├─ welcome/     (onboarding wizard)
  └─ popup/       (browser action popup + auth)
        │
        │ Supabase auth (OAuth popup → `tabmail.ai/auth/tb-callback`)
        ▼
Cloudflare Worker backend (`api.tabmail.ai` / `dev.tabmail.ai`)
  ├─ Bearer token auth + consent gate
  ├─ Entitlements from KV + quota/throttle via usage worker
  └─ LLM completions + server tools

---

Key directories

The add-on is split into several MV3 “background modules” (see manifest.json → background.scripts):

Core modules

• agent/: Message workflows (processing, tagging, summaries, reminders), plus some privileged integrations via experiments.
• chat/: Chat window UI (chat.html/chat.js/chat.css), tool orchestration, and chat-specific modules.
  • chat/tools/ — Tool implementations for email, calendar, contacts, web, and knowledge base operations.
  • chat/fsm/ — Finite state machines for multi-step workflows (compose, delete, archive, calendar CRUD, etc.).
  • chat/modules/ — Core chat functionality (context, converse, markdown, SSE/WS tools, etc.).
• compose/: Composer integration for smart compose and inline edits.
• fts/: Local search/indexing via native FTS helper (required); see fts/README.md.

UI and configuration

• theme/: Theme system + palette; see theme/README.md and theme/palette/README.md.
• config/: Options UI and settings modules.
• gui/: UI tweaks and layout helpers (some via experiments).
• popup/: The extension popup and auth helpers.
• welcome/: Onboarding wizard with multi-page setup flow.

User customization

• prompts/: Custom user prompts UI — allows users to define custom action, composition, and knowledge base prompts.
• templates/: Email templates system — user-defined email templates with variable substitution.
• marketplace/: Community template marketplace — browse and install shared templates.

Support

• keepalive/: Keep-alive and lifecycle helpers (via experiment tmKeepAlive).
• icons/: SVG icons used by the add-on (tab icon, sort icons, view mode icons).

---

Experiments

Experiments are defined in manifest.json under experiment_apis and implemented under the corresponding */experiments/ folders.

Use experiments only when the Thunderbird WebExtension API cannot provide the needed integration point.

Current experiments by module:

Module	Experiments
keepalive/	tmKeepAlive
chat/	tmCalendar, glodaSearch, messageSelection, tmWebFetch
agent/	tmMsgNotify, tmHdr
theme/	keyOverride, threadTooltip, tagSort, threadPaneDisplayToggle, tmTheme, tmMessageListCardView, tmMessageListTableView, tmPreviewGate, threadMessages
gui/	tmPrefs, tmTweaks, tmUpdates

---

Theming

All colors come from the palette system:

• Source of truth: theme/palette/palette.data.json
• Docs: theme/palette/README.md
• Theme system overview: theme/README.md
• Architecture deep dive: theme/README_ARCHITECTURE.md

---

Full-text search (FTS)

FTS is implemented in fts/ and uses a native messaging host (Rust binary with bundled SQLite + FTS5) for fast local indexing.

The native FTS helper is required — it powers both email search and chat memory features.

The native FTS helper is source-available: github.com/TabMail/tabmail-native-fts

Features

• Email search — Fast full-text search across all indexed emails with stemming, synonyms, and BM25 ranking. Also provides fast access to email content and metadata.
• Memory search — Chat history is indexed locally, allowing the agent to recall past conversations
• Memory read — Retrieve full chat sessions by timestamp for context continuity

See fts/README.md for architecture and operational notes.

---

Backend integration

The add-on calls the TabMail backend at:

• Production: https://api.tabmail.ai
• Development: https://dev.tabmail.ai

Authentication is via Supabase access tokens; the add-on uses the hosted TB callback page:

• https://tabmail.ai/auth/tb-callback

Backend details (routing, auth, quota/throttle, endpoints) are to be released later as API docs.

---

Development

• Load temporarily: Thunderbird → Tools → Developer Tools → Debug Add-ons → “Load Temporary Add-on” → select tabmail-thunderbird/manifest.json
• Options page: config/config.html
• Chat shortcut: see manifest.json → commands.open-chat-window

---

License

This project is open source under the Mozilla Public License 2.0 (MPL-2.0).

• Free to use, modify, and distribute — including commercially.
• MPL is a weak-copyleft license at file granularity: modifications to MPL-licensed files must stay open, but you may combine them with proprietary code in larger works.

Copyright © Lisem AI Ltd.

See:

• LICENSE
• THIRD_PARTY_LICENSES.md — bundled third-party libraries

---

Contributing

We welcome contributions! This project uses the Developer Certificate of Origin (DCO) — sign off every commit with git commit -s.

See CONTRIBUTING.md for details.

---

Trademarks

"TabMail" is a trademark of Lisem AI Ltd. This license does not grant permission to use the TabMail name or branding.

See TRADEMARKS.md.