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.
getListedMessages([tabId], [options])
– [Added in TB 121]
Lists the messages in the current view, honoring sort order and filters as used in the UI. Sort order of the returned messages can be overridden via the options parameter
Parameters
tabId
Defaults to the active tab of the current window.
options
sortOrder
sortType
Specifies how the returned messages should be sorted. This does not change the actual sort of the displayed messages. Default sort order is descending, if not specified otherwise. Returning sorted messages is faster than manually sorting the messages afterwards, but slower than returning the messages in their original order.
Supported values:
author
date
flagged
junk
junkScore
priority
read
recipients
size
subject
tags
Required permissions
getSelectedFolders([tabId])
– [Added in TB 129]
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
layout
The arrangement of the folder pane, message list pane, and message display pane.
Supported values:
standard
The standard layout with the folder pane on the left, and the message list and message display stacked on the right.
vertical
The vertical layout with the folder pane, message list, and message display side by side in three columns.
wide
The wide layout with the folder pane and message list side by side on top, and the message display on the bottom.
tabId
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.
groupType
messagePaneVisible
Whether the message pane is visible or not.
sortOrder
sortType
The primary sort column of the message list.
Supported values:
account
Sort by account, grouping messages belonging to the same account.
attachments
Sort by attachment status.
author
Sort by author.
correspondent
Sort by correspondents.
custom
Sort by a custom column.
date
Sort by date.
flagged
Sort by starred status.
id
Sort by the Message-ID header, a unique identifier assigned by the sending server.
junkStatus
Sort by spam status.
location
Sort by folder location.
none
Not sorted.
priority
Sort by priority.
received
Sort by received date.
recipient
Sort by recipient.
size
Sort by message size.
status
Sort by message status.
subject
Sort by subject.
tags
Sort by tags.
thread
Sort by thread, grouping messages that belong to the same conversation.
unread
Sort by unread status.
MailTabProperties
– [Added in TB 121]
object
displayedFolderId
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.
groupType
layout
Sets the arrangement of the folder pane, message list pane, and message display pane. Setting a layout will be applied to all mail tabs.
Supported values:
standard
The standard layout with the folder pane on the left, and the message list and message display stacked on the right.
vertical
The vertical layout with the folder pane, message list, and message display side by side in three columns.
wide
The wide layout with the folder pane and message list side by side on top, and the message display on the bottom.
messagePaneVisible
Shows or hides the message display pane.
sortOrder
sortType
Sorts the list of messages. sortOrder must also be given.
Supported values:
account
Sort by account, grouping messages belonging to the same account.
attachments
Sort by attachment status.
author
Sort by author.
correspondent
Sort by correspondents.
custom
Sort by a custom column.
date
Sort by date.
flagged
Sort by starred status.
id
Sort by the Message-ID header, a unique identifier assigned by the sending server.
junkStatus
Sort by spam status.
location
Sort by folder location.
none
Not sorted.
priority
Sort by priority.
received
Sort by received date.
recipient
Sort by recipient.
size
Sort by message size.
status
Sort by message status.
subject
Sort by subject.
tags
Sort by tags.
thread
Sort by thread, grouping messages that belong to the same conversation.
unread
Sort by unread status.
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.