runtime API

Hint

The runtime API is inherited from Firefox, and its primary documentation is maintained by Mozilla at MDN. Thunderbird implements only the subset of functions, events, and types listed here. The MDN pages may provide further details and examples, but they may also reference features that are not supported in Thunderbird.

Use the browser.runtime API to retrieve the background page, return details about the manifest, and listen for and respond to events in the app or extension lifecycle. You can also use this API to convert the relative path of URLs to fully-qualified URLs.

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.

nativeMessaging

nativeMessaging

Exchange messages with programs other than Thunderbird.

userScripts

userScripts

Allow unverified third-party scripts to access your data.

Functions

connect([extensionId], [connectInfo])

– [Added in TB 45]

Attempts to connect to connect listeners within an extension/app (such as the background page), or other extensions/apps. This is useful for content scripts connecting to their extension processes, inter-app/extension communication, and web messaging. Note that this does not connect to any listeners in a content script. Extensions may connect to content scripts embedded in tabs via connect(tabId, [connectInfo]).

Parameters

extensionId

[extensionId]

(string, optional)

The ID of the extension or app to connect to. If omitted, a connection will be attempted with your own extension. Required if sending messages from a web page for web messaging.

connectInfo

[connectInfo]

(object, optional)

includeTlsChannelId

[includeTlsChannelId]

(boolean, optional)

Whether the TLS channel ID will be passed into onConnectExternal for processes that are listening for the connection event.

name

[name]

(string, optional)

Will be passed into onConnect for processes that are listening for the connection event.

Return type (Promise)

_returns

Port through which messages can be sent and received. The port’s runtime.^port on^disconnect event is fired if the extension/app does not exist.

connectNative(application)

– [Added in TB 50]

Connects to a native application in the host machine.

Parameters

application

application

(string)

The name of the registered application to connect to.

Return type (Promise)

_returns

Port through which messages can be sent and received with the application

Required permissions

  • nativeMessaging

getBackgroundPage()

– [Added in TB 45]

Retrieves the JavaScript ‘window’ object for the background page running inside the current extension/app. If the background page is an event page, the system will ensure it is loaded before calling the callback. If there is no background page, an error is set.

Note

If this is called from a page that is part of a private browsing window, such as a sidebar in a private window or a popup opened from a private window, then it will always return null.

Return type (Promise)

_returns

The JavaScript ‘window’ object for the background page.

getBrowserInfo()

– [Added in TB 51]

Returns information about the current browser.

Return type (Promise)

_returns

getContexts(filter)

– [Added in TB 127]

Fetches information about active contexts associated with this extension

Parameters

filter

filter

(runtime.^context^filter)

A filter to find matching context.

Return type (Promise)

_returns

The matching contexts, if any.

getFrameId(target)

– [Added in TB 96]

Get the frameId of any window global or frame element.

Parameters

target

target

(any)

A WindowProxy or a Browsing Context container element (IFrame, Frame, Embed, Object) for the target frame.

Return type (Promise)

_returns

number

The frameId of the target frame, or -1 if it doesn’t exist.

getManifest()

– [Added in TB 45]

Returns details about the app or extension from the manifest. The object returned is a serialization of the full manifest file.

Note

Returns null for missing values, and removes unsupported keys.

Return type (Promise)

_returns

object

The manifest details.

getPlatformInfo()

– [Added in TB 45]

Returns information about the current platform.

Return type (Promise)

_returns

getURL(path)

– [Added in TB 45]

Converts a relative path within an app/extension install directory to a fully-qualified URL.

Parameters

path

path

(string)

A path to a resource within an app/extension expressed relative to its install directory.

Return type (Promise)

_returns

string

The fully-qualified URL to the resource.

openOptionsPage()

– [Added in TB 48]

Open your Extension’s options page, if possible.The precise behavior may depend on your manifest’s options_ui or options_page key, or what the browser happens to support at the time.If your Extension does not declare an options page, or the browser failed to create one for some other reason, the callback will set lastError.

reload()

– [Added in TB 51]

Reloads the app or extension.

restart()

Restart the device when the app runs in kiosk mode. Otherwise, it’s no-op.

sendMessage([extensionId], message, [options])

– [Added in TB 45]

Sends a single message to event listeners within your extension/app or a different extension/app. Similar to connect([extensionId], [connectInfo]) but only sends a single message, with an optional response. If sending to your extension, the onMessage event will be fired in each page, or onMessageExternal, if a different extension. Note that extensions cannot send messages to content scripts using this method. To send messages to content scripts, use sendMessage(tabId, message, [options]).

Parameters

extensionId

[extensionId]

(string, optional)

The ID of the extension/app to send the message to. If omitted, the message will be sent to your own extension/app. Required if sending messages from a web page for web messaging.

message

message

(any)

options

[options]

(object, optional)

includeTlsChannelId

[includeTlsChannelId]

(boolean, optional) Unsupported.

Whether the TLS channel ID will be passed into onMessageExternal for processes that are listening for the connection event.

Return type (Promise)

_returns

any

The JSON response object sent by the handler of the message. If an error occurs while connecting to the extension, the callback will be called with no arguments and lastError will be set to the error message.

sendNativeMessage(application, message)

– [Added in TB 50]

Send a single message to a native application.

Parameters

application

application

(string)

The name of the native messaging host.

message

message

(any)

The message that will be passed to the native messaging host.

Return type (Promise)

_returns

any

The response message sent by the native messaging host. If an error occurs while connecting to the native messaging host, the callback will be called with no arguments and lastError will be set to the error message.

Required permissions

  • nativeMessaging

setUninstallURL([url])

Sets the URL to be visited upon uninstallation. This may be used to clean up server-side data, do analytics, and implement surveys. Maximum 1023 characters.

Parameters

url

[url]

(string, optional)

URL to be opened after the extension is uninstalled. This URL must have an http: or https: scheme. Set an empty string to not open a new tab upon uninstallation.

Events

onConnect

– [Added in TB 45]

Fired when a connection is made from either an extension process or a content script.

Parameters for onConnect.addListener(listener)

listener(port)

listener(port)

A function that will be called when this event occurs.

Parameters passed to the listener function

port

port

(Port)

onConnectExternal

– [Added in TB 54]

Fired when a connection is made from another extension.

Parameters for onConnectExternal.addListener(listener)

listener(port)

listener(port)

A function that will be called when this event occurs.

Parameters passed to the listener function

port

port

(Port)

onInstalled

– [Added in TB 52]

Fired when the extension is first installed, when the extension is updated to a new version, and when the browser is updated to a new version.

Note

Before version 55, this event is not triggered for temporarily installed add-ons.

Parameters for onInstalled.addListener(listener)

listener(details)

listener(details)

A function that will be called when this event occurs.

Parameters passed to the listener function

details

details

(object)

reason

The reason that this event is being dispatched.

temporary

temporary

(boolean)

– [Added in TB 55]

Indicates whether the addon is installed as a temporary extension.

id

[id]

(string, optional) Unsupported.

Indicates the ID of the imported shared module extension which updated. This is present only if ‘reason’ is ‘shared_module_update’.

previousVersion

[previousVersion]

(string, optional)

– [Added in TB 55]

Indicates the previous version of the extension, which has just been updated. This is present only if ‘reason’ is ‘update’.

onMessage

– [Added in TB 45]

Fired when a message is sent from either an extension process or a content script.

Parameters for onMessage.addListener(listener)

listener(message, sender, sendResponse)

listener(message, sender, sendResponse)

A function that will be called when this event occurs.

Parameters passed to the listener function

message

[message]

(any, optional)

The message sent by the calling script.

sender

sender

sendResponse

sendResponse

(function)

Function to call (at most once) when you have a response. The argument should be any JSON-ifiable object. If you have more than one onMessage listener in the same document, then only one may send a response. This function becomes invalid when the event listener returns, unless you return true from the event listener to indicate you wish to send a response asynchronously (this will keep the message channel open to the other end until sendResponse is called).

Expected return value of the listener function

runtime-on-message-returns

boolean

Return true from the event listener if you wish to call sendResponse after the event listener returns.

onMessageExternal

– [Added in TB 54]

Fired when a message is sent from another extension/app. Cannot be used in a content script.

Parameters for onMessageExternal.addListener(listener)

listener(message, sender, sendResponse)

listener(message, sender, sendResponse)

A function that will be called when this event occurs.

Parameters passed to the listener function

message

[message]

(any, optional)

The message sent by the calling script.

sender

sender

sendResponse

sendResponse

(function)

Function to call (at most once) when you have a response. The argument should be any JSON-ifiable object. If you have more than one onMessage listener in the same document, then only one may send a response. This function becomes invalid when the event listener returns, unless you return true from the event listener to indicate you wish to send a response asynchronously (this will keep the message channel open to the other end until sendResponse is called).

Expected return value of the listener function

runtime-on-message-external-returns

boolean

Return true from the event listener if you wish to call sendResponse after the event listener returns.

onPerformanceWarning

– [Added in TB 124]

Fired when a runtime performance issue is detected with the extension. Observe this event to be proactively notified of runtime performance problems with the extension.

Parameters for onPerformanceWarning.addListener(listener)

listener(details)

listener(details)

A function that will be called when this event occurs.

Parameters passed to the listener function

details

details

(object)

category

The performance warning event category, e.g. ‘content_script’.

description

description

(string)

An explanation of what the warning means, and hopefully how to address it.

severity

The performance warning event severity, e.g. ‘high’.

tabId

[tabId]

(integer, optional)

The Tab that the performance warning relates to, if any.

onStartup

– [Added in TB 52]

Fired when a profile that has this extension installed first starts up. This event is not fired for incognito profiles.

Parameters for onStartup.addListener(listener)

listener()

listener()

A function that will be called when this event occurs.

onSuspend

– [Added in TB 100]

Sent to the event page just before it is unloaded. This gives the extension opportunity to do some clean up. Note that since the page is unloading, any asynchronous operations started while handling this event are not guaranteed to complete. If more activity for the event page occurs before it gets unloaded the onSuspendCanceled event will be sent and the page won’t be unloaded.

Note

This event does not fire until Thunderbird 106, when event pages are available.

Parameters for onSuspend.addListener(listener)

listener()

listener()

A function that will be called when this event occurs.

onSuspendCanceled

– [Added in TB 100]

Sent after onSuspend to indicate that the app won’t be unloaded after all.

Note

This event does not fire until Thunderbird 106, when event pages are available.

Parameters for onSuspendCanceled.addListener(listener)

listener()

listener()

A function that will be called when this event occurs.

onUpdateAvailable

– [Added in TB 51]

Fired when an update is available, but isn’t installed immediately because the app is currently running. If you do nothing, the update will be installed the next time the background page gets unloaded, if you want it to be installed sooner you can explicitly call reload(). If your extension is using a persistent background page, the background page of course never gets unloaded, so unless you call reload() manually in response to this event the update will not get installed until the next time the browser itself restarts. If no handlers are listening for this event, and your extension has a persistent background page, it behaves as if reload() is called in response to this event.

Parameters for onUpdateAvailable.addListener(listener)

listener(details)

listener(details)

A function that will be called when this event occurs.

Parameters passed to the listener function

details

details

(object)

The manifest details of the available update.

version

version

(string)

The version number of the available update.

onUserScriptConnect

– [Added in TB 136]

Fired when a connection is made from a USER_SCRIPT world registered through the userScripts API.

Note

Available for use with Manifest V3 only.

Note

Requires the userScripts permission.

Parameters for onUserScriptConnect.addListener(listener)

listener(port)

listener(port)

A function that will be called when this event occurs.

Parameters passed to the listener function

port

port

(Port)

Required permissions

  • userScripts

onUserScriptMessage

– [Added in TB 136]

Fired when a message is sent from a USER_SCRIPT world registered through the userScripts API.

Note

Available for use with Manifest V3 only.

Note

Requires the userScripts permission.

Parameters for onUserScriptMessage.addListener(listener)

listener(message, sender, sendResponse)

listener(message, sender, sendResponse)

A function that will be called when this event occurs.

Parameters passed to the listener function

message

[message]

(any, optional)

The message sent by the calling script.

sender

sender

sendResponse

sendResponse

(function)

Function to call (at most once) when you have a response. The argument should be any JSON-ifiable object. If you have more than one onMessage listener in the same document, then only one may send a response. This function becomes invalid when the event listener returns, unless you return true from the event listener to indicate you wish to send a response asynchronously (this will keep the message channel open to the other end until sendResponse is called).

Expected return value of the listener function

runtime-on-user-script-message-returns

boolean

Return true from the event listener if you wish to call sendResponse after the event listener returns.

Required permissions

  • userScripts

Types

BrowserInfo

An object containing information about the current browser.

object

buildID

buildID

(string)

The browser’s build ID/date, for example ‘20160101’.

name

name

(string)

The name of the browser, for example ‘Thunderbird’.

vendor

vendor

(string)

The name of the browser vendor, for example ‘Mozilla’.

version

version

(string)

The browser’s version, for example ‘42.0.0’ or ‘0.8.1pre’.

ContextType

The type of extension view.

string

Supported values:

BACKGROUND

BACKGROUND

POPUP

POPUP

SIDE_PANEL

SIDE_PANEL

TAB

TAB

Event

– [Added in TB ≤53]

An object which allows the addition and removal of listeners for a Chrome event.

object

ExtensionContext

A context hosting extension content

object

contextId

contextId

(string)

An unique identifier associated to this context

contextType

contextType

The type of the context

frameId

frameId

(integer)

The frame ID for this context, or -1 if it is not hosted in a frame.

incognito

incognito

(boolean)

Whether the context is associated with an private browsing context.

tabId

tabId

(integer)

The tab ID for this context, or -1 if it is not hosted in a tab.

windowId

windowId

(integer)

The window ID for this context, or -1 if it is not hosted in a window.

documentId

[documentId]

(string, optional) Unsupported.

An UUID for the document associated with this context, or undefined if it is not hosted in a document

documentOrigin

[documentOrigin]

(string, optional)

The origin of the document associated with this context, or undefined if it is not hosted in a document

documentUrl

[documentUrl]

(string, optional)

The URL of the document associated with this context, or undefined if it is not hosted in a document

MessageSender

– [Added in TB 45]

An object containing information about the script context that sent a message or request.

Note

Before version 54, ‘id’ was the add-on’s internal UUID, not the add-on ID.

object

frameId

[frameId]

(integer, optional)

The frame that opened the connection. 0 for top-level frames, positive for child frames. This will only be set when tab is set.

id

[id]

(string, optional)

The ID of the extension or app that opened the connection, if any.

tab

[tab]

(Tab, optional)

The Tab which opened the connection, if any. This property will only be present when the connection was opened from a tab (including content scripts), and only if the receiver is an extension, not an app.

tlsChannelId

[tlsChannelId]

(string, optional) Unsupported.

The TLS channel ID of the page or frame that opened the connection, if requested by the extension or app, and if available.

url

[url]

(string, optional)

The URL of the page or frame that opened the connection. If the sender is in an iframe, it will be iframe’s URL not the URL of the page which hosts it.

userScriptWorldId

[userScriptWorldId]

(string, optional)

The worldId of the USER_SCRIPT world that sent the message. Only present on onUserScriptMessage and onUserScriptConnect (in port.sender) events.

OnInstalledReason

– [Added in TB 45]

The reason that this event is being dispatched.

string

Supported values:

browser_update

browser_update

install

install

update

update

OnPerformanceWarningCategory

– [Added in TB 124]

The performance warning event category, e.g. ‘content_script’.

string

Supported values:

content_script

content_script

OnPerformanceWarningSeverity

– [Added in TB 124]

The performance warning event severity. Will be ‘high’ for serious and user-visible issues.

string

Supported values:

high

high

low

low

medium

medium

OnRestartRequiredReason

– [Added in TB 45]

The reason that the event is being dispatched. ‘app_update’ is used when the restart is needed because the application is updated to a newer version. ‘os_update’ is used when the restart is needed because the browser/OS is updated to a newer version. ‘periodic’ is used when the system runs for more than the permitted uptime set in the enterprise policy.

string

Supported values:

app_update

app_update

os_update

os_update

periodic

periodic

PlatformArch

– [Added in TB 45]

The machine’s processor architecture.

string

Supported values:

aarch64

aarch64

arm

arm

noarch

noarch

ppc64

ppc64

s390x

s390x

sparc64

sparc64

x86-32

x86-32

x86-64

x86-64

PlatformInfo

– [Added in TB 45]

An object containing information about the current platform.

object

arch

arch

The machine’s processor architecture.

nacl_arch

nacl_arch

(runtime.^platform^nacl^arch) Unsupported.

The native client architecture. This may be different from arch on some platforms.

os

The operating system the browser is running on.

PlatformOs

– [Added in TB 45]

The operating system the browser is running on.

string

Supported values:

android

android

cros

cros

linux

linux

mac

mac

openbsd

openbsd

win

win

Port

– [Added in TB 45]

An object which allows two way communication with other pages.

object

disconnect

disconnect

(function)

name

name

(string)

onDisconnect

onDisconnect

(Event)

onMessage

onMessage

(Event)

postMessage

postMessage

(function)

sender

[sender]

(MessageSender, optional)

This property will only be present on ports passed to onConnect/onConnectExternal listeners.

RequestUpdateCheckStatus

Result of the update check.

string

Supported values:

no_update

no_update

throttled

throttled

update_available

update_available

Properties

id

The ID of the extension/app.

lastError

This will be defined during an API method callback if there was an error