mailTabs API
The mailTabs API first appeared in Thunderbird 66 and allows to interact with Thunderbirds main mail window.
Functions
create([createProperties])
– [Added in TB 121]
Creates a new mail tab. Standard tab properties can be adjusted via update([tabId], updateProperties) after the mail tab has been created. Note: A new mail window can be created via create([createData]).
Parameters
get(tabId)
Get the properties of a mail tab.
Parameters
tabId
(integer)
ID of the requested mail tab. Throws if the requested tab is not a mail tab.
getCurrent()
Get the properties of the active mail tab, if the active tab is a mail tab. Returns undefined otherwise.
getListedMessages([tabId])
– [Added in TB 121]
Lists the messages in the current view, honoring sort order and filters.
Parameters
[tabId]
(integer, optional)
Defaults to the active tab of the current window.
Return type (Promise)
Required permissions
getSelectedMessages([tabId])
Lists the selected messages in the current folder.
Parameters
[tabId]
(integer, optional)
Defaults to the active tab of the current window.
Return type (Promise)
Required permissions
query([queryInfo])
Gets all mail tabs that have the specified properties, or all mail tabs if no properties are specified.
Parameters
[queryInfo]
(object, optional)
[active]
(boolean, optional)
Whether the tabs are active in their windows.
[currentWindow]
(boolean, optional)
Whether the tabs are in the current window.
[lastFocusedWindow]
(boolean, optional)
Whether the tabs are in the last focused window.
[windowId]
(integer, optional)
The ID of the parent window, or WINDOW_ID_CURRENT for the current window.
setQuickFilter([tabId], properties)
Sets the Quick Filter user interface based on the options specified.
Parameters
[tabId]
(integer, optional)
Defaults to the active tab of the current window.
properties
(object)
[attachment]
(boolean, optional)
Shows only messages with attachments.
[contact]
(boolean, optional)
Shows only messages from people in the address book.
[flagged]
(boolean, optional)
Shows only flagged messages.
[show]
(boolean, optional)
Shows or hides the Quick Filter bar.
Shows only messages with tags on them.
Shows only messages matching the supplied text.
[unread]
(boolean, optional)
Shows only unread messages.
setSelectedMessages([tabId], messageIds)
Selects none, one or multiple messages.
Parameters
[tabId]
(integer, optional)
Defaults to the active tab of the current window.
The IDs of the messages, which should be selected. The mail tab will switch to the folder of the selected messages. Throws if they belong to different folders. Array can be empty to deselect any currently selected message.
Required permissions
update([tabId], updateProperties)
Modifies the properties of a mail tab. Properties that are not specified in updateProperties are not modified.
Parameters
[tabId]
(integer, optional)
Defaults to the active tab of the current window.
Events
onDisplayedFolderChanged
Fired when the displayed folder changes in any mail tab.
Parameters for onDisplayedFolderChanged.addListener(listener)
listener(tab, displayedFolder)
A function that will be called when this event occurs.
Parameters passed to the listener function
- Changes in TB 76:
previously just the tab’s ID
Required permissions
onSelectedMessagesChanged
Fired when the selected messages change in any mail tab.
Parameters for onSelectedMessagesChanged.addListener(listener)
listener(tab, selectedMessages)
A function that will be called when this event occurs.
Parameters passed to the listener function
- Changes in TB 76:
previously just the tab’s ID
Required permissions
Types
MailTab
object
active
(boolean)
id
(integer)
layout
(string)
Supported values:
standard
wide
vertical
windowId
(integer)
The permission is required for this property to be included.
[folderPaneVisible]
(boolean, optional)
[messagePaneVisible]
(boolean, optional)
[sortOrder]
(string, optional)
Note: sortType and sortOrder depend on each other, so both should be present, or neither.
Supported values:
none
ascending
descending
[sortType]
(string, optional)
Note: sortType and sortOrder depend on each other, so both should be present, or neither.
Supported values:
none
date
subject
author
id
thread
priority
status
size
flagged
unread
recipient
location
tags
junkStatus
attachments
account
custom
received
correspondent
[viewType]
(string, optional)
– [Added in TB 91]
Supported values:
ungrouped
groupedByThread
groupedBySortType
MailTabProperties
object
Sets the folder displayed in the mail tab. Requires the permission. The previous message selection in the given folder will be restored, if any. This property is ignored, if selectedMessages is specified.
[folderPaneVisible]
(boolean, optional)
Shows or hides the folder pane.
[layout]
(string, optional)
Sets the arrangement of the folder pane, message list pane, and message display pane. Note that setting this applies it to all mail tabs.
Supported values:
standard
wide
vertical
[messagePaneVisible]
(boolean, optional)
Shows or hides the message display pane.
[sortOrder]
(string, optional)
Sorts the list of messages. sortType must also be given.
Supported values:
none
ascending
descending
[sortType]
(string, optional)
Sorts the list of messages. sortOrder must also be given.
Supported values:
none
date
subject
author
id
thread
priority
status
size
flagged
unread
recipient
location
tags
junkStatus
attachments
account
custom
received
correspondent
[viewType]
(string, optional)
Supported values:
ungrouped
groupedByThread
groupedBySortType
QuickFilterTextDetail
object
text
(string)
String to match against the recipients, author, subject, or body.
[author]
(boolean, optional)
Shows messages where text matches the author.
[body]
(boolean, optional)
Shows messages where text matches the message body.
[recipients]
(boolean, optional)
Shows messages where text matches the recipients.
[subject]
(boolean, optional)
Shows messages where text matches the subject.