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 128.0]

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]).

Parameters

createProperties

[createProperties]

(MailTabProperties, optional)



Return type (Promise)

_returns

MailTab



Details about the created mail tab. Will contain the ID of the new tab.

get(tabId)

– [Added in TB 91.0]

Get the MailTab properties of a mail tab.

Parameters

tabId

tabId

(integer)



ID of the requested mail tab. Throws if the requested tabId does not belong to a mail tab.

Return type (Promise)

_returns

MailTab



getCurrent()

– [Added in TB 68.0]

Get the MailTab properties of the active mail tab. Returns undefined, if the active tab is not a mail tab.

Return type (Promise)

_returns

MailTab

– [Added in TB 91.0]



getListedMessages([tabId], [options])

– [Added in TB 128.0]

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

[tabId]

(integer, optional)



Defaults to the active tab of the current window.

options

[options]

(object, optional)



sortOrder

[sortOrder]

(string, optional)

– [Added in TB 153.0]



The sort order for the returned messages. Ignored if sortType is not specified.

Supported values:

ascending



descending



sortType

[sortType]

(string, optional)

– [Added in TB 153.0]



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

Return type (Promise)

_returns

MessageList

– [Added in TB 153.0]



Required permissions

messagesRead

getSelectedFolders([tabId])

– [Added in TB 128.0]

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.

Parameters

tabId

[tabId]

(integer, optional)



Defaults to the active tab of the current window.

Return type (Promise)

_returns

array of MailFolder



Required permissions

accountsRead

getSelectedMessages([tabId])

– [Added in TB 68.0]

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.

Parameters

tabId

[tabId]

(integer, optional)



Defaults to the active tab of the current window.

Return type (Promise)

_returns

MessageList

– [Added in TB 91.0]



Required permissions

messagesRead

query([queryInfo])

– [Added in TB 68.0]

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

Parameters

queryInfo

[queryInfo]

(object, optional)



active

[active]

(boolean, optional)



Whether the tabs are active in their windows.

currentWindow

[currentWindow]

(boolean, optional)



Whether the tabs are in the current window.

lastFocusedWindow

[lastFocusedWindow]

(boolean, optional)



Whether the tabs are in the last focused window.

windowId

[windowId]

(integer, optional)



The ID of the parent window, or WINDOW_ID_CURRENT for the current window.

Return type (Promise)

_returns

array of MailTab

– [Added in TB 91.0]



setQuickFilter([tabId], properties)

– [Added in TB 68.0]

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

Parameters

tabId

[tabId]

(integer, optional)



Defaults to the active tab of the current window.

properties

properties

(object)



attachment

[attachment]

(boolean, optional)



Shows only messages with attachments.

contact

[contact]

(boolean, optional)



Shows only messages from people in the address book.

flagged

[flagged]

(boolean, optional)



Shows only flagged messages.

show

[show]

(boolean, optional)



Shows or hides the Quick Filter bar.

tags

[tags]

(boolean or TagsDetail, optional)



Shows only messages with tags on them.

text

[text]

(QuickFilterTextDetail, optional)



Shows only messages matching the supplied text.

unread

[unread]

(boolean, optional)



Shows only unread messages.

setSelectedMessages([tabId], messageIds)

– [Added in TB 102.3.3]

Selects none, one or multiple messages. Opens collapsed threads to show the selection, if required.

Parameters

tabId

[tabId]

(integer, optional)



Defaults to the active tab of the current window.

messageIds

messageIds

(array of MessageId)



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

accountsRead
messagesRead

update([tabId], updateProperties)

– [Added in TB 68.0]

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

Parameters

tabId

[tabId]

(integer, optional)



Defaults to the active tab of the current window.

updateProperties

updateProperties

(MailTabProperties)



Return type (Promise)

_returns

MailTab

– [Added in TB 128.0]



Details about the updated mail tab.

Events

onDisplayedFolderChanged

– [Added in TB 68.0]

Fired when the displayed folder changes in any mail tab.

Parameters for onDisplayedFolderChanged.addListener(listener)

listener(tab, displayedFolder)

listener(tab, displayedFolder)



A function that will be called when this event occurs.

Parameters passed to the listener function

tab

tab

(Tab)

– [Added in TB 78.0]



displayedFolder

displayedFolder

(MailFolder)

– [Added in TB 78.0]



Required permissions

accountsRead

onSelectedMessagesChanged

– [Added in TB 68.0]

Fired when the selected messages change in any mail tab.

Parameters for onSelectedMessagesChanged.addListener(listener)

listener(tab, selectedMessages)

listener(tab, selectedMessages)



A function that will be called when this event occurs.

Parameters passed to the listener function

tab

tab

(Tab)

– [Added in TB 78.0]



selectedMessages

selectedMessages

(MessageList)

– [Added in TB 78.0]



Required permissions

messagesRead

Types

FolderMode

– [Added in TB 128.0]

A supported folder mode in the folder pane.

string

Supported values:

all



Show all folders.

favorite



Show only favorite folders.

recent



Show recently used folders.

tags



Show virtual tag folders.

unified



Show the unified folder view.

unread



Show only folders with unread messages.

MailTab

– [Added in TB 91.0]

object

active

active

(boolean)



id

id

(integer)



layout

layout

(string)



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.

windowId

windowId

(integer)



displayedFolder

[displayedFolder]

(MailFolder, optional)



The folder displayed in the mail tab. The accountsRead permission is required for this property to be included.

folderMode

[folderMode]

(FolderMode, optional)

– [Added in TB 128.0]



The folder mode of the currently displayed folder.

folderModesEnabled

[folderModesEnabled]

(array of FolderMode, optional)

– [Added in TB 128.0]



The enabled folder modes in the folder pane, and their sort order.

folderPaneVisible

[folderPaneVisible]

(boolean, optional)



Whether the folder pane is visible or not.

messagePaneVisible

[messagePaneVisible]

(boolean, optional)



Whether the message pane is visible or not.

sortOrder

[sortOrder]

(string, optional)



The sort order of the message list.

Supported values:

ascending



Ascending sort order.

descending



Descending sort order.

none



No sort order.

sortType

[sortType]

(string, optional)



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.

viewType

[viewType]

(string, optional)



Grouping type of the message list.

Supported values:

groupedBySortType



Messages are grouped by the current sort type.

groupedByThread



Messages are grouped by threads.

ungrouped



Messages are not grouped.

MailTabProperties

– [Added in TB 128.0]

object

displayedFolder

[displayedFolder]

(MailFolderId or MailFolder, optional)



Sets the folder displayed in the mail tab. Requires the accountsRead permission. The previous message selection in the given folder will be restored, if any.

folderMode

[folderMode]

(FolderMode, optional)



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

[folderModesEnabled]

(array of FolderMode, optional)



Set the enabled folder modes in the folder pane, and their sort order.

folderPaneVisible

[folderPaneVisible]

(boolean, optional)



Shows or hides the folder pane.

layout

[layout]

(string, optional)



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

[messagePaneVisible]

(boolean, optional)



Shows or hides the message display pane.

sortOrder

[sortOrder]

(string, optional)



Sorts the list of messages. sortType must also be given.

Supported values:

ascending



Ascending sort order.

descending



Descending sort order.

none



No sort order.

sortType

[sortType]

(string, optional)



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.

viewType

[viewType]

(string, optional)



Sets the grouping type of displayed messages.

Supported values:

groupedBySortType



Messages are grouped by the current sort type.

groupedByThread



Messages are grouped by threads.

ungrouped



Messages are not grouped.

QuickFilterTextDetail

– [Added in TB 68.0]

object

text

text

(string)



String to match against the recipients, author, subject, or body.

author

[author]

(boolean, optional)



Shows messages where text matches the author.

body

[body]

(boolean, optional)



Shows messages where text matches the message body.

recipients

[recipients]

(boolean, optional)



Shows messages where text matches the recipients.

subject

[subject]

(boolean, optional)



Shows messages where text matches the subject.