mailTabs

The messages API first appeared in Thunderbird 66 (see bug 1499617).

The Filter and Layout sample extensions use this API.

Functions

query(queryInfo)

Gets all mail tabs that have the specified properties, or all mail tabs if no properties are specified.

  • queryInfo (object)
    • [active] (boolean) Whether the tabs are active in their windows.
    • [currentWindow] (boolean) Whether the tabs are in the current window.
    • [lastFocusedWindow] (boolean) Whether the tabs are in the last focused window.
    • [windowId] (integer) The ID of the parent window, or WINDOW_ID_CURRENT for the current window.

Returns a Promise fulfilled with:

update([tabId], updateProperties)

Modifies the properties of a mail tab. Properties that are not specified in updateProperties are not modified.

  • [tabId] (integer) Defaults to the active tab of the current window.
  • updateProperties (object)
    • [displayedFolder] (MailFolder) Sets the folder displayed in the tab. The extension must have an accounts permission to do this.
    • [folderPaneVisible] (boolean) Shows or hides the folder pane.
    • [layout] (string) Sets the arrangement of the folder pane, message list pane, and message display pane. Note that setting this applies it to all mail tabs.
    • [messagePaneVisible] (boolean) Shows or hides the message display pane.
    • [sortOrder] (string) Sorts the list of messages. sortType must also be given.
    • [sortType] (string) Sorts the list of messages. sortOrder must also be given.

Values for layout:

  • standard
  • wide
  • vertical

Values for sortOrder:

  • none
  • ascending
  • descending

Values for sortType:

  • none
  • date
  • subject
  • author
  • id
  • thread
  • priority
  • status
  • size
  • flagged
  • unread
  • recipient
  • location
  • tags
  • junkStatus
  • attachments
  • account
  • custom
  • received
  • correspondent

getSelectedMessages([tabId])

Lists the selected messages in the current folder. A messages permission is required to do this.

  • [tabId] (integer) Defaults to the active tab of the current window.

Returns a Promise fulfilled with:

Note

The permission messagesRead is required to use getSelectedMessages.

setQuickFilter([tabId], properties)

Sets the Quick Filter user interface based on the options specified.

  • [tabId] (integer) Defaults to the active tab of the current window.
  • properties (object)
    • [attachment] (boolean) Shows only messages with attachments.
    • [contact] (boolean) Shows only messages from people in the address book.
    • [flagged] (boolean) Shows only flagged messages.
    • [show] (boolean) Shows or hides the Quick Filter bar.
    • [tags] (boolean or TagsDetail) Shows only messages with tags on them.
    • [text] (QuickFilterTextDetail) Shows only messages matching the supplied text.
    • [unread] (boolean) Shows only unread messages.

Events

onDisplayedFolderChanged(tab, displayedFolder)

Fired when the displayed folder changes in any mail tab.

  • tab (Tab) Changed in Thunderbird 76, previously just the tab’s ID
  • displayedFolder (MailFolder)

Note

The permission accountsRead is required to use onDisplayedFolderChanged.

onSelectedMessagesChanged(tab, selectedMessages)

Fired when the selected messages change in any mail tab.

  • tab (Tab) Changed in Thunderbird 76, previously just the tab’s ID
  • selectedMessages (MessageList)

Note

The permission messagesRead is required to use onSelectedMessagesChanged.

Types

MailTab

object:

  • active (boolean)
  • displayedFolder (MailFolder) The accountsRead permission is required.
  • folderPaneVisible (boolean)
  • id (integer)
  • layout (string)
  • messagePaneVisible (boolean)
  • sortOrder (string)
  • sortType (string)
  • windowId (integer)

Values for layout:

  • standard
  • wide
  • vertical

Values for sortOrder:

  • none
  • ascending
  • descending

Values for sortType:

  • none
  • date
  • subject
  • author
  • id
  • thread
  • priority
  • status
  • size
  • flagged
  • unread
  • recipient
  • location
  • tags
  • junkStatus
  • attachments
  • account
  • custom
  • received
  • correspondent

QuickFilterTextDetail

object:

  • text (string) String to match against the recipients, author, subject, or body.
  • [author] (boolean) Shows messages where text matches the author.
  • [body] (boolean) Shows messages where text matches the message body.
  • [recipients] (boolean) Shows messages where text matches the recipients.
  • [subject] (boolean) Shows messages where text matches the subject.