Proposal: high-level message-list action API

[ussmarines]

Proposal: high-level message-list action API

Problem

Thunderbird WebExtensions can interact with messages through standard APIs and can add context-menu entries, toolbar/action buttons and message-display UI. There is currently no standard high-level entry point for an extension-owned action attached directly to each visible message row in the thread pane.

Some add-ons therefore use privileged Experiments to manipulate about:3pane DOM structures directly. That couples add-ons to Thunderbird internals and makes review and long-term compatibility difficult.

Proposed capability

Add a reusable MessageListAction Experiment draft that lets an extension:

1. register one message-list action with a title and extension icon;
2. provide ephemeral per-message presentation state (visible, enabled, active, optional title override);
3. receive a WebExtension event when the user invokes the action;
4. receive standard WebExtension message/tab objects rather than Thunderbird internals.

The implementation would own all thread-pane DOM integration. Extensions would not receive DOM nodes, gDBView, message headers, folder URIs or native message keys.

Example uses

• follow-up / reminder extensions;
• CRM or ticket-linking extensions;
• bookmarking / triage tools;
• task integrations;
• custom message-state workflows.

Proposed shape

await browser.MessageListAction.register({
  title: "Track message",
  icons: {"16": "icons/track-16.svg", "32": "icons/track-32.svg"}
});

await browser.MessageListAction.setState(message.id, {
  active: true,
  title: "Stop tracking message"
});

browser.MessageListAction.onClicked.addListener((message, tab) => {
  // Extension business logic.
});

Additional methods proposed for discussion:

• update(details)
• unregister()
• clearState(messageId)
• clearAllStates()

Design principles

The API is deliberately high-level and narrow. It does not expose arbitrary message-list customization, custom columns, raw DOM injection, XUL, internal message keys, persistence, or application-specific concepts.

The Experiment owns lifecycle cleanup. Presentation state is ephemeral; persistent state remains the extension's responsibility.

Questions for maintainers

1. Is a dedicated row action an acceptable stable UI primitive for the message list?
2. Should the namespace follow an existing action API naming pattern instead of MessageListAction?
3. Should the first draft support one action per extension or a collection of actions?
4. Should state be push-based (setState) or requested lazily through an event/callback when rows render?
5. Which message identifier/conversion path should the Experiment use so the public boundary remains aligned with the standard messages API?
6. Should this be explored as a core API directly rather than maintained as a longer-lived Experiment?

Prototype

A minimal schema/sample/prototype implementation has been prepared separately. It intentionally keeps application logic outside the Experiment and can be reshaped based on this design discussion before a PR is opened.

[freaktechnik]

We've had https://searchfox.org/comm-central/rev/5631a57ef8994fce81d10552da2e640f1de90020/mail/base/content/modules/ThreadPaneColumns.mjs#501 for this kind of use for a long time now, I think there is some experiment for using that out there somewhere? The part that hasn't really been determined yet is how that would work for the cards view and I guess an extension API should optimally also work there without any effort from the author.

[jobisoft]

The new API design is tightly coupled to the new message database, so we might delay an official API until that is fully settled.

[ussmarines]

Thanks, that helps clarify the direction.

I looked into ThreadPaneColumns and existing add-on Experiments using it. It does appear to be the right existing primitive for table view: addCustomColumn() already owns native column registration and works with nsIMsgDBHdr callbacks. XNote's customColumn Experiment is one concrete example, and other add-ons are doing similar thin wrappers around ThreadPaneColumns.

The important limitation is exactly the one mentioned above: custom columns are currently table-view only. The cards layout uses a fixed set of fields, so a wrapper around ThreadPaneColumns alone would not give an extension a no-effort cross-layout API.

I also have a small prototype of the higher-level abstraction from this issue running on Thunderbird 154.0. I tested it against two separate real profiles forced to the native table and cards layouts. In both modes it injects exactly one action, delivers onClicked using standard WebExtension MessageHeader/tab objects, leaves native read flags and folder counters unchanged, and cleans up on uninstall. The prototype currently performs its own DOM integration for cards/table, so I would not propose that implementation as final if Thunderbird prefers the table side to be backed by ThreadPaneColumns.

Given the new-message-database work, would a useful next step be to treat this as a transitional Experiment design rather than a core API proposal for now: use ThreadPaneColumns as the table-view backend where possible, keep a small cards-view adapter behind the same high-level WebExtension-facing contract, and revisit the backend once the new message database/API design settles?

If that direction is useful, I can reshape the prototype that way before opening any PR. If you would rather avoid introducing even a transitional Experiment until the new database design is settled, I am also happy to hold off and use this issue only to capture the desired cross-layout contract.