mailTabs API
The mailTabs API allows to interact with Thunderbird’s main mail tab (a.k.a 3-pane tab).
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.
accountsRead
See your mail accounts, their identities and their folders.
messagesRead
Read your email messages.
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. A new mail window can be created via create([createData]).
get(tabId)
– [Added in TB 89]
Get the MailTab properties of a mail tab.
Parameters
tabId
ID of the requested mail tab. Throws if the requested tabId does not belong to a mail tab.
getCurrent()
– [Added in TB 66]
Get the MailTab properties of the active mail tab. Returns undefined, if the active tab is not a mail tab.
getListedMessages([tabId])
– [Added in TB 121]
Lists the messages in the current view, honoring sort order and filters.
Required permissions
getSelectedFolders([tabId])
– [Added in TB 128]
Lists the selected folders in the folder pane. Does not include folders which are context-clicked, but not selected. The context-clicked folders are always returned by the onClicked event of the menus API.
Required permissions
getSelectedMessages([tabId])
– [Added in TB 66]
Lists the selected messages in the current folder. Includes messages in collapsed threads. Does not include messages which are context-clicked, but not selected. The context-clicked messages are always returned by the onClicked event of the menus API.
Required permissions
query([queryInfo])
– [Added in TB 66]
Gets all mail tabs that have the specified properties, or all mail tabs if no properties are specified.
Parameters
queryInfo
active
Whether the tabs are active in their windows.
currentWindow
Whether the tabs are in the current window.
lastFocusedWindow
Whether the tabs are in the last focused window.
windowId
The ID of the parent window, or WINDOW_ID_CURRENT for the current window.
setQuickFilter([tabId], properties)
– [Added in TB 66]
Sets the Quick Filter user interface based on the options specified.
Parameters
tabId
Defaults to the active tab of the current window.
properties
attachment
Shows only messages with attachments.
contact
Shows only messages from people in the address book.
flagged
Shows only flagged messages.
show
Shows or hides the Quick Filter bar.
tags
Shows only messages with tags on them.
text
Shows only messages matching the supplied text.
unread
Shows only unread messages.
setSelectedMessages([tabId], messageIds)
– [Added in TB 106]
Selects none, one or multiple messages. Opens collapsed threads to show the selection, if required.
Parameters
tabId
Defaults to the active tab of the current window.
messageIds
Required permissions
update([tabId], updateProperties)
– [Added in TB 66]
Modifies the properties of a mail tab. Properties that are not specified in updateProperties are not modified.
Parameters
tabId
Defaults to the active tab of the current window.
updateProperties
Events
onDisplayedFolderChanged
– [Added in TB 66]
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
tab
displayedFolder
Required permissions
onSelectedMessagesChanged
– [Added in TB 66]
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
tab
selectedMessages
Required permissions
Types
FolderMode
– [Added in TB 127]
A supported folder mode in the folder pane.
MailTab
– [Added in TB 89]
object
active
id
layout
windowId
displayedFolder
The folder displayed in the mail tab. The permission is required for this property to be included.
folderMode
The folder mode of the currently displayed folder.
folderModesEnabled
The enabled folder modes in the folder pane, and their sort order.
folderPaneVisible
Whether the folder pane is visible or not.
messagePaneVisible
Whether the message pane is visible or not.
sortOrder
sortType
The primary sort column of the message list.
Supported values:
account
attachments
author
correspondent
custom
date
flagged
id
junkStatus
location
none
priority
received
recipient
size
status
subject
tags
thread
unread
viewType
MailTabProperties
– [Added in TB 121]
object
displayedFolder
Sets the folder displayed in the mail tab. Requires the permission. The previous message selection in the given folder will be restored, if any.
folderMode
Sets the currently used folder mode, enabling it if required. If used without also specifying displayedFolder, the currently selected folder is re-selected in the new folder mode, if possible.
folderModesEnabled
Set the enabled folder modes in the folder pane, and their sort order.
folderPaneVisible
Shows or hides the folder pane.
layout
messagePaneVisible
Shows or hides the message display pane.
sortOrder
sortType
Sorts the list of messages. sortOrder must also be given.
Supported values:
account
attachments
author
correspondent
custom
date
flagged
id
junkStatus
location
none
priority
received
recipient
size
status
subject
tags
thread
unread
viewType
QuickFilterTextDetail
– [Added in TB 66]
object
text
String to match against the recipients, author, subject, or body.
author
Shows messages where text matches the author.
body
Shows messages where text matches the message body.
recipients
Shows messages where text matches the recipients.
subject
Shows messages where text matches the subject.