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
Exchange messages with programs other than Thunderbird.
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
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
includeTlsChannelId
Whether the TLS channel ID will be passed into onConnectExternal for processes that are listening for the connection event.
name
Will be passed into onConnect for processes that are listening for the connection event.
connectNative(application)
– [Added in TB 50]
Connects to a native application in the host machine.
Return type (Promise)
_returns
Required permissions
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.
getBrowserInfo()
– [Added in TB 51]
Returns information about the current browser.
getContexts(filter)
– [Added in TB 127]
Fetches information about active contexts associated with this extension
getFrameId(target)
– [Added in TB 96]
Get the frameId of any window global or frame element.
Parameters
target
A WindowProxy or a Browsing Context container element (IFrame, Frame, Embed, Object) for the target frame.
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.
getPlatformInfo()
– [Added in TB 45]
Returns information about the current platform.
getURL(path)
– [Added in TB 45]
Converts a relative path within an app/extension install directory to a fully-qualified URL.
Parameters
path
A path to a resource within an app/extension expressed relative to its install directory.
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
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
options
sendNativeMessage(application, message)
– [Added in TB 50]
Send a single message to a native application.
Parameters
application
The name of the native messaging host.
message
The message that will be passed to the native messaging host.
Return type (Promise)
_returns
Required permissions
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 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)
A function that will be called when this event occurs.
onConnectExternal
– [Added in TB 54]
Fired when a connection is made from another extension.
Parameters for onConnectExternal.addListener(listener)
listener(port)
A function that will be called when this event occurs.
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)
A function that will be called when this event occurs.
Parameters passed to the listener function
details
reason
The reason that this event is being dispatched.
temporary
Indicates whether the addon is installed as a temporary extension.
id
Indicates the ID of the imported shared module extension which updated. This is present only if ‘reason’ is ‘shared_module_update’.
previousVersion
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)
A function that will be called when this event occurs.
Parameters passed to the listener function
message
The message sent by the calling script.
sender
sendResponse
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
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)
A function that will be called when this event occurs.
Parameters passed to the listener function
message
The message sent by the calling script.
sender
sendResponse
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
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)
A function that will be called when this event occurs.
Parameters passed to the listener function
details
category
The performance warning event category, e.g. ‘content_script’.
description
An explanation of what the warning means, and hopefully how to address it.
severity
The performance warning event severity, e.g. ‘high’.
tabId
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()
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()
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()
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)
A function that will be called when this event occurs.
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)
A function that will be called when this event occurs.
Required permissions
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)
A function that will be called when this event occurs.
Parameters passed to the listener function
message
The message sent by the calling script.
sender
sendResponse
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
Return true from the event listener if you wish to call sendResponse after the event listener returns.
Required permissions
Types
BrowserInfo
An object containing information about the current browser.
object
buildID
The browser’s build ID/date, for example ‘20160101’.
name
The name of the browser, for example ‘Thunderbird’.
vendor
The name of the browser vendor, for example ‘Mozilla’.
version
The browser’s version, for example ‘42.0.0’ or ‘0.8.1pre’.
ContextType
The type of extension view.
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
An unique identifier associated to this context
contextType
The type of the context
frameId
The frame ID for this context, or -1 if it is not hosted in a frame.
incognito
Whether the context is associated with an private browsing context.
tabId
The tab ID for this context, or -1 if it is not hosted in a tab.
windowId
The window ID for this context, or -1 if it is not hosted in a window.
documentId
An UUID for the document associated with this context, or undefined if it is not hosted in a document
documentOrigin
The origin of the document associated with this context, or undefined if it is not hosted in a document
documentUrl
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
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
The ID of the extension or app that opened the connection, if any.
tab
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
The TLS channel ID of the page or frame that opened the connection, if requested by the extension or app, and if available.
url
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
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.
OnPerformanceWarningCategory
– [Added in TB 124]
The performance warning event category, e.g. ‘content_script’.
string
OnPerformanceWarningSeverity
– [Added in TB 124]
The performance warning event severity. Will be ‘high’ for serious and user-visible issues.
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.
PlatformArch
– [Added in TB 45]
The machine’s processor architecture.
PlatformInfo
– [Added in TB 45]
An object containing information about the current platform.
object
arch
The machine’s processor architecture.
nacl_arch
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.
Port
– [Added in TB 45]
An object which allows two way communication with other pages.
object
disconnect
name
onDisconnect
onMessage
postMessage
sender
This property will only be present on ports passed to onConnect/onConnectExternal listeners.
RequestUpdateCheckStatus
Result of the update check.
Properties
id
The ID of the extension/app.
lastError
This will be defined during an API method callback if there was an error