spaces API

The spaces API allows to manage built-in and custom spaces, and to add buttons for custom spaces to Thunderbird’s spaces toolbar.

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.

contextualIdentities

contextualIdentities

Grant access to some or all methods of the contextualIdentities API.

cookies

cookies

Grant access to some or all methods of the cookies API.

management

management

Monitor extension usage and manage themes.

Functions

create(name, tabProperties, [buttonProperties])

– [Added in TB 115]

Creates a new space and adds its button to the spaces toolbar.

Parameters

name

name

(string)

The name to assign to this space. May only contain alphanumeric characters and underscores. Must be unique for this extension.

tabProperties

tabProperties

(string or SpaceTabProperties)

The properties for the new tab being opened, when the associated button in the spaces toolbar is clicked. Either a string specifying the default URL, or a SpaceTabProperties object. The URL may point to a WebExtension page or a web page.

buttonProperties

[buttonProperties]

(SpaceButtonProperties, optional)

Properties of the button in the spaces toolbar for the new space.

Return type (Promise)

_returns

get(spaceId)

– [Added in TB 115]

Retrieves details about the specified space.

Parameters

spaceId

spaceId

(integer)

The id of the space.

Return type (Promise)

_returns

open(spaceId, [windowId])

– [Added in TB 115]

Opens or switches to the specified space. Throws an exception if the requested space does not exist or was not created by this extension.

Parameters

spaceId

spaceId

(integer)

The id of the space.

windowId

[windowId]

(integer, optional)

The id of the normal window, where the space should be opened. Defaults to the most recent normal window.

Return type (Promise)

_returns

Details about the opened or activated space tab.

query([queryInfo])

– [Added in TB 115]

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

Parameters

queryInfo

[queryInfo]

(object, optional)

extensionId

[extensionId]

(string, optional)

Id of the extension which should own the spaces. The management permission is required to be able to match against extension ids.

id

[id]

(integer, optional)

The id of the space.

isBuiltIn

[isBuiltIn]

(boolean, optional)

Spaces should be default Thunderbird spaces.

isSelfOwned

[isSelfOwned]

(boolean, optional)

Spaces should have been created by this extension.

name

[name]

(string, optional)

The name of the spaces (names are not unique).

Return type (Promise)

_returns

array of Space

remove(spaceId)

– [Added in TB 115]

Removes the specified space, closes all its tabs and removes its button from the spaces toolbar. Throws an exception if the requested space does not exist or was not created by this extension.

Parameters

spaceId

spaceId

(integer)

The id of the space.

update(spaceId, tabProperties, [buttonProperties])

– [Added in TB 115]

Updates the specified space. Throws an exception if the requested space does not exist or was not created by this extension.

Parameters

spaceId

spaceId

(integer)

The id of the space.

tabProperties

tabProperties

The properties for the new tab being opened, when the associated button in the spaces toolbar is clicked. Either a string specifying the default URL, or a SpaceTabProperties object. The URL may point to a WebExtension page or a web page.

buttonProperties

[buttonProperties]

(SpaceButtonProperties, optional)

Properties of the button in the spaces toolbar for the specified space Only specified button properties will be updated.

Types

ColorArray

– [Added in TB 115]

An array of four integers in the range [0,255] that make up the RGBA color. For example, opaque red is [255, 0, 0, 255].

array of integer

ExtensionFileUrl

string

ExtensionURL

A path relative to the root of the extension.

string

IconPath

Either a string to specify a relative path of a single icon to be used for all sizes, or a dictionary object to specify paths for multiple icons in different sizes, so the icon does not have to be scaled for a device with a different pixel density. Each entry is a name-value pair with value being a relative path to an icon file, and name its size. Example:

{
  "16": "icon16.png",
  "32": "icon32.png"
}

See the MDN documentation about choosing icon sizes for more information on this topic.

object

or

Space

– [Added in TB 115]

object

id

id

(integer)

The id of the space.

isBuiltIn

isBuiltIn

(boolean)

Whether this space is one of the default Thunderbird spaces, or an extension space.

isSelfOwned

isSelfOwned

(boolean)

Whether this space was created by this extension.

name

name

(string)

The name of the space. Names are unique for a single extension, but different extensions may use the same name.

extensionId

[extensionId]

(string, optional)

The id of the extension which owns the space. The management permission is required to include this property.

SpaceButtonProperties

– [Added in TB 115]

Properties of a button in the spaces toolbar.

object

badgeBackgroundColor

[badgeBackgroundColor]

(string or ColorArray, optional)

Sets the background color of the badge. Can be specified as an array of four integers in the range [0,255] that make up the RGBA color of the badge. For example, opaque red is [255, 0, 0, 255]. Can also be a string with an HTML color name (red) or a HEX color value (#FF0000 or #F00). Reset when set to an empty string.

badgeText

[badgeText]

(string, optional)

Sets the badge text for the button in the spaces toolbar. The badge is displayed on top of the icon. Any number of characters can be set, but only about four can fit in the space. Removed when set to an empty string.

defaultIcons

[defaultIcons]

(string or IconPath, optional)

The paths to one or more icons for the button in the spaces toolbar. Reset to the extension icon, when set to an empty string.

themeIcons

[themeIcons]

(array of ThemeIcons, optional)

Specifies dark and light icons for the button in the spaces toolbar to be used with themes: The light icons will be used on dark backgrounds and vice versa. At least the set for 16px icons should be specified. The set for 32px icons will be used on screens with a very high pixel density, if specified. Reset when set to an empty array.

title

[title]

(string, optional)

The title for the button in the spaces toolbar, used in the tooltip of the button and as the displayed name in the overflow menu. Reset to the name of the extension, when set to an empty string.

SpaceTabProperties

– [Added in TB 135]

Properties for the new tab being opened by clicking on the associated button in the spaces toolbar.

object

cookieStoreId

[cookieStoreId]

(string, optional)

The CookieStore id used by the tab. Either a custom id created using the contextualIdentities API, or a built-in one: firefox-default, firefox-container-1, firefox-container-2, firefox-container-3, firefox-container-4, firefox-container-5.

Note

The naming pattern of the built-in cookie stores was deliberately not changed for Thunderbird, but kept for compatibility reasons.

Note

The cookies permission is required to be able to specify this property. Furthermore, the contextualIdentities permission should be requested, to enable the contextual identities feature (enabled by default only on Thunderbird Daily).

linkHandler

[linkHandler]

(string, optional)

– [Added in TB 136]

Thunderbird is a mail client, not a browser. It is possible to load a web page, but opening follow-up pages through hyperlinks should be handled by the user’s default browser. This property specifies to what extent this behavior should be enforced. The default balanced link handler will open links to the same host directly in Thunderbird, everything else will be opened in the user’s default browser. A relaxed link handler will open all links inside of Thunderbird, a strict link handler will open all links in the user’s default browser, except links to the same page.

Supported values:

balanced

balanced

relaxed

relaxed

strict

strict

url

[url]

(string, optional)

The default URL. May point to a WebExtension page or a web page.

ThemeIcons

Define a set of icons for themes depending on whether Thunderbird detects that the theme uses dark or light text. All provided URLs must be relative to the manifest.json file.

object

dark

dark

The dark icon to use for light themes

light

light

A light icon to use for dark themes

size

size

(integer)

The size of the icons