Skip to content

feat(plugins): let a plugin display its own result set in the message list - #955

Open
aspuru wants to merge 1 commit into
bulwarkmail:mainfrom
aspuru:plugin-show-messages
Open

feat(plugins): let a plugin display its own result set in the message list#955
aspuru wants to merge 1 commit into
bulwarkmail:mainfrom
aspuru:plugin-show-messages

Conversation

@aspuru

@aspuru aspuru commented Sep 2, 2026

Copy link
Copy Markdown

Implements api.search.showMessages(ids, label) as described in #954: a plugin that does its own
retrieval can hand the host a set of email ids and a label, and the host renders exactly those
messages in the message list.

What it does

await api.search.showMessages(ids, "5 messages about the tariff decision");

The list shows those messages and the label appears where a search term normally would, so the
user can see why the list looks that way and clear it like any other search.

Clearing rules

Both are covered by tests, and the second one is the non-obvious one:

  • Typing a search replaces a plugin's list. A user's own search always wins.
  • Changing folder clears a plugin's list but NOT a user's search. A search is deliberately kept
    across folders and scoped by searchMailboxId. A plugin-supplied set has no equivalent scope, so
    carrying it into another folder would silently reinterpret it — it is dropped instead.

Scope and safety

  • ui:message-list permission, declared alongside the existing capabilities.
  • Read-only and session-scoped. The host fetches with the user's own JMAP client, so a plugin
    cannot surface a message the user could not already open. Strictly weaker than tabs.categorize,
    which writes keywords.
  • Capped at 200 ids per call. A result set is a list a human reads, not a bulk export; the cap
    keeps one call from pulling a whole mailbox through Email/get.

Tests

stores/__tests__/email-store-show-messages.test.ts — 10 tests covering the isPluginList
lifecycle and both clearing rules. Passing against this branch:

✓ stores/__tests__/email-store-show-messages.test.ts (10 tests) 7ms
  Test Files  1 passed (1)
       Tests  10 passed (10)

eslint reports no new problems; the warnings it emits on this tree are pre-existing.

Notes

Based on 1.9.2. Happy to change the name, the signature, or the clearing semantics — the shape
here is what fell out of using it rather than a strong opinion, and I'd rather match your
preference than land it as-is.

… list

Adds `api.search.showMessages(ids, label)`. A plugin that does its own
retrieval can hand the host a list of email ids and a label, and the host
renders exactly those messages in the message list, with the label shown where
a search term normally appears.

Today a plugin can read messages and draw its own UI, but the message list is
closed to it: category tabs only filter into the fixed buckets, and `api.ui`
has no navigation. The nearest workaround is emitting a search query for the
user to run, which only works when the result set happens to be expressible as
a query.

Two clearing rules, both covered by tests:

- Typing a search replaces a plugin's list, so a user's own search always wins.
- Changing folder clears a plugin's list but NOT a user's search. A search is
  deliberately kept across folders upstream and scoped by `searchMailboxId`; a
  plugin-supplied set has no equivalent scope, so it is dropped rather than
  silently reinterpreted.

Closes bulwarkmail#954
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant