messageDisplay API

A message can be displayed in either Thunderbird’s main mail tab (a.k.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.

Permissions

The following permissions influence the behavior of the API. Depending on which permissions are requested, additional methods might be available, or certain data may be included in responses.

Hint

Request permissions only when needed. Unnecessary requests may result in rejection during ATN review.

messagesRead

messagesRead

Read your email messages.

Note

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

Functions

getDisplayedMessage([tabId])

– [Added in TB 70]

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

Parameters

tabId

[tabId]

(integer, optional)

Return type (Promise)

_returns

MessageHeader or null

– [Added in TB 96]

Required permissions

  • messagesRead

getDisplayedMessages([tabId])

– [Added in TB 81]

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

Parameters

tabId

[tabId]

(integer, optional)

Return type (Promise)

_returns

array of MessageHeader

– [Added in TB 96]

Required permissions

  • messagesRead

open(openProperties)

– [Added in TB 102]

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

Parameters

openProperties

openProperties

(object)

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

active

[active]

(boolean, optional)

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

file

[file]

(File, optional)

– [Added in TB 114]

The DOM file object of a message to be opened.

headerMessageId

[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

[location]

(string, optional)

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

Supported values:

tab

tab

window

window

messageId

[messageId]

(MessageId, optional)

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

windowId

[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)

_returns

Required permissions

  • messagesRead

Events

onMessageDisplayed

– [Added in TB 70]

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)

listener(tab, message)

A function that will be called when this event occurs.

Parameters passed to the listener function

tab

tab

(Tab)

message

message

Required permissions

  • messagesRead

onMessagesDisplayed

– [Added in TB 81]

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)

listener(tab, messages)

A function that will be called when this event occurs.

Parameters passed to the listener function

tab

tab

(Tab)

messages

messages

(array of MessageHeader)

Required permissions

  • messagesRead