messageDisplay API

The message display API first appeared in Thunderbird 68.

A message can be displayed in either a 3-pane tab, a tab of its own, or in a window of its own. All are referenced by tabId in this API. Display windows are considered to have exactly one tab, which has limited functionality compared to tabs from the main window.

Note

The permission messagesRead is required to use messenger.messageDisplay.*.

Functions

getDisplayedMessage(tabId)

Gets the currently displayed message in the specified tab (even if the tab itself is currently not visible). It returns null if no messages are displayed, or if multiple messages are displayed.

Parameters

tabId

(integer)

Return type (Promise)

MessageHeader or null

Required permissions

  • messagesRead

getDisplayedMessages(tabId)

– [Added in TB 81, backported to TB 78.4.0]

Gets an array of the currently displayed messages in the specified tab (even if the tab itself is currently not visible). The array is empty if no messages are displayed.

Parameters

tabId

(integer)

Return type (Promise)

array of MessageHeader

Required permissions

  • messagesRead

open(openProperties)

– [Added in TB 102]

Opens a message in a new tab or in a new window.

Parameters

openProperties

(object)

Settings for opening the message. Exactly one of messageId, headerMessageId or file must be specified.

[active]

(boolean, optional)

Whether the new tab should become the active tab in the window. Only applicable to messages opened in tabs.

[file]

(File, optional)

The DOM file object of a message to be opened.

[headerMessageId]

(string, optional)

The headerMessageId of a message to be opened. Will throw an ExtensionError, if the provided headerMessageId is unknown or invalid. Not supported for external messages.

[location]

(string, optional)

Where to open the message. If not specified, the users preference is honoured.

Supported values:

tab

window

[messageId]

(MessageId, optional)

The id of a message to be opened. Will throw an ExtensionError, if the provided messageId is unknown or invalid.

[windowId]

(integer, optional)

The id of the window, where the new tab should be created. Defaults to the current window. Only applicable to messages opened in tabs.

Return type (Promise)

Tab

Required permissions

  • messagesRead

Events

onMessageDisplayed

Fired when a message is displayed, whether in a 3-pane tab, a message tab, or a message window.

Parameters for onMessageDisplayed.addListener(listener)

listener(tab, message)

A function that will be called when this event occurs.

Parameters passed to the listener function

tab

(Tab)

Changes in TB 76:

previously just the tab’s ID

message

Required permissions

  • messagesRead

onMessagesDisplayed

– [Added in TB 81, backported to TB 78.4.0]

Fired when either a single message is displayed or when multiple messages are displayed, whether in a 3-pane tab, a message tab, or a message window.

Parameters for onMessagesDisplayed.addListener(listener)

listener(tab, messages)

A function that will be called when this event occurs.

Parameters passed to the listener function

tab

(Tab)

messages

(array of MessageHeader)

Required permissions

  • messagesRead