scripting API
Hint
The scripting 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 scripting API to execute script in different contexts.
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.
scripting
Grant access to some or all methods of the scripting API.
Functions
executeScript(injection)
– [Added in TB 102]
Injects a script into a target context. The script will be run at document_idle.
Required permissions
getRegisteredContentScripts([filter])
– [Added in TB 102]
Returns all dynamically registered content scripts for this extension that match the given filter.
Parameters
filter
An object to filter the extension’s dynamically registered scripts.
Required permissions
insertCSS(injection)
– [Added in TB 102]
Inserts a CSS stylesheet into a target context. If multiple frames are specified, unsuccessful injections are ignored.
Required permissions
registerContentScripts(scripts)
– [Added in TB 102]
Registers one or more content scripts for this extension.
Parameters
scripts
Contains a list of scripts to be registered. If there are errors during script parsing/file validation, or if the IDs specified already exist, then no scripts are registered.
Required permissions
removeCSS(injection)
– [Added in TB 102]
Removes a CSS stylesheet that was previously inserted by this extension from a target context.
Parameters
injection
The details of the styles to remove. Note that the css, files, and origin properties must exactly match the stylesheet inserted through insertCSS. Attempting to remove a non-existent stylesheet is a no-op.
Required permissions
unregisterContentScripts([filter])
– [Added in TB 102]
Unregisters one or more content scripts for this extension.
Parameters
filter
If specified, only unregisters dynamic content scripts which match the filter. Otherwise, all of the extension’s dynamic content scripts are unregistered.
Required permissions
updateContentScripts(scripts)
– [Added in TB 102]
Updates one or more content scripts for this extension.
Parameters
scripts
Contains a list of scripts to be updated. If there are errors during script parsing/file validation, or if the IDs specified do not already exist, then no scripts are updated.
Required permissions
Types
ContentScriptFilter
object
ids
The IDs of specific scripts to retrieve with getRegisteredContentScripts() or to unregister with unregisterContentScripts().
CSSInjection
object
target
Details specifying the target into which to inject the CSS.
css
A string containing the CSS to inject. Exactly one of files and css must be specified.
files
The path of the CSS files to inject, relative to the extension’s root directory. Exactly one of files and css must be specified.
origin
CSSOrigin
– [Added in TB 53]
The origin of the CSS to inject, this affects the cascading order (priority) of the stylesheet.
ExecutionWorld
– [Added in TB 102]
The JavaScript world for a script to execute within. ISOLATED is the default execution environment of content scripts, MAIN is the web page’s execution environment.
ExtensionURL
A path relative to the root of the extension.
string
InjectionResult
Result of a script injection.
object
frameId
The frame ID associated with the injection.
error
The error property is set when the script execution failed. The value is typically an (Error) object with a message property, but could be any value (including primitives and undefined) if the script threw or rejected with such a value.
result
The result of the script execution.
InjectionTarget
– [Added in TB 102]
object
tabId
The ID of the tab into which to inject.
allFrames
Whether the script should inject into all frames within the tab. Defaults to false. This must not be true if frameIds is specified.
frameIds
The IDs of specific frames to inject into.
RegisteredContentScript
– [Added in TB 102]
object
id
The id of the content script, specified in the API call.
allFrames
If specified true, it will inject into all frames, even if the frame is not the top-most frame in the tab. Each frame is checked independently for URL requirements; it will not inject into child frames if the URL requirements are not met. Defaults to false, meaning that only the top frame is matched.
css
The list of CSS files to be injected into matching pages. These are injected in the order they appear in this array.
cssOrigin
excludeMatches
Excludes pages that this content script would otherwise be injected into.
js
The list of JavaScript files to be injected into matching pages. These are injected in the order they appear in this array.
matches
Specifies which pages this content script will be injected into. Must be specified for registerContentScripts().
matchOriginAsFallback
If matchOriginAsFallback is true, then the code is also injected in about:, data:, blob: when their origin matches the pattern in ‘matches’, even if the actual document origin is opaque (due to the use of CSP sandbox or iframe sandbox). Match patterns in ‘matches’ must specify a wildcard path glob. By default it is false.
persistAcrossSessions
Specifies if this content script will persist into future sessions. Defaults to true.
Note
Since Thunderbird 105, this option is optional and accepts any boolean value.
Note
Prior to Thunderbird 105, this option was required and only accepted the false value.
runAt
Specifies when JavaScript files are injected into the web page. The preferred and default value is document_idle.
world
The JavaScript world for a script to execute within. Defaults to “ISOLATED”.
RunAt
– [Added in TB 45]
The soonest that the JavaScript or CSS will be injected into the tab.
ScriptInjection
Details of a script injection
object
target
Details specifying the target into which to inject the script.
args
The arguments to curry into a provided function. This is only valid if the func parameter is specified. These arguments must be JSON-serializable.
files
The path of the JS files to inject, relative to the extension’s root directory. Exactly one of files and func must be specified.
func
A JavaScript function to inject. This function will be serialized, and then deserialized for injection. This means that any bound parameters and execution context will be lost. Exactly one of files and func must be specified.
injectImmediately
Whether the injection should be triggered in the target as soon as possible (but not necessarily prior to page load).
world