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

scripting

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

Note

The permission scripting is required to use messenger.scripting.*.

Functions

executeScript(injection)

– [Added in TB 102]

Injects a script into a target context. The script will be run at document_idle.

Parameters

injection

injection

The details of the script which to inject.

Return type (Promise)

_returns

array of InjectionResult

Required permissions

  • scripting

getRegisteredContentScripts([filter])

– [Added in TB 102]

Returns all dynamically registered content scripts for this extension that match the given filter.

Parameters

filter

[filter]

(ContentScriptFilter, optional)

An object to filter the extension’s dynamically registered scripts.

Return type (Promise)

_returns

Required permissions

  • scripting

insertCSS(injection)

– [Added in TB 102]

Inserts a CSS stylesheet into a target context. If multiple frames are specified, unsuccessful injections are ignored.

Parameters

injection

injection

The details of the styles to insert.

Required permissions

  • scripting

registerContentScripts(scripts)

– [Added in TB 102]

Registers one or more content scripts for this extension.

Parameters

scripts

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

  • scripting

removeCSS(injection)

– [Added in TB 102]

Removes a CSS stylesheet that was previously inserted by this extension from a target context.

Parameters

injection

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

  • scripting

unregisterContentScripts([filter])

– [Added in TB 102]

Unregisters one or more content scripts for this extension.

Parameters

filter

[filter]

(ContentScriptFilter, optional)

If specified, only unregisters dynamic content scripts which match the filter. Otherwise, all of the extension’s dynamic content scripts are unregistered.

Required permissions

  • scripting

updateContentScripts(scripts)

– [Added in TB 102]

Updates one or more content scripts for this extension.

Parameters

scripts

scripts

(array of object)

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

  • scripting

Types

ContentScriptFilter

object

ids

[ids]

(array of string, optional)

The IDs of specific scripts to retrieve with getRegisteredContentScripts() or to unregister with unregisterContentScripts().

CSSInjection

object

target

target

Details specifying the target into which to inject the CSS.

css

[css]

(string, optional)

A string containing the CSS to inject. Exactly one of files and css must be specified.

files

[files]

(array of string, optional)

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

[origin]

(string, optional)

The style origin for the injection. Defaults to ‘AUTHOR’.

Supported values:

AUTHOR

AUTHOR

USER

USER

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.

string

Supported values:

ISOLATED

ISOLATED

MAIN

MAIN

– [Added in TB 128]

ExtensionURL

A path relative to the root of the extension.

string

InjectionResult

Result of a script injection.

object

frameId

frameId

(integer)

The frame ID associated with the injection.

error

[error]

(any, optional)

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

[result]

(any, optional)

The result of the script execution.

InjectionTarget

– [Added in TB 102]

object

tabId

tabId

(number)

The ID of the tab into which to inject.

allFrames

[allFrames]

(boolean, optional)

Whether the script should inject into all frames within the tab. Defaults to false. This must not be true if frameIds is specified.

frameIds

[frameIds]

(array of number, optional)

The IDs of specific frames to inject into.

RegisteredContentScript

– [Added in TB 102]

object

id

id

(string)

The id of the content script, specified in the API call.

allFrames

[allFrames]

(boolean, optional)

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

[css]

(array of ExtensionURL, optional)

The list of CSS files to be injected into matching pages. These are injected in the order they appear in this array.

excludeMatches

[excludeMatches]

(array of string, optional)

Excludes pages that this content script would otherwise be injected into.

js

[js]

(array of ExtensionURL, optional)

The list of JavaScript files to be injected into matching pages. These are injected in the order they appear in this array.

matches

[matches]

(array of string, optional)

Specifies which pages this content script will be injected into. Must be specified for registerContentScripts().

matchOriginAsFallback

[matchOriginAsFallback]

(boolean, optional)

– [Added in TB 128]

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

[persistAcrossSessions]

(boolean, optional)

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

[runAt]

(RunAt, optional)

Specifies when JavaScript files are injected into the web page. The preferred and default value is document_idle.

world

[world]

(ExecutionWorld, optional)

– [Added in TB 128]

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.

string

Supported values:

document_end

document_end

document_idle

document_idle

document_start

document_start

ScriptInjection

Details of a script injection

object

target

target

Details specifying the target into which to inject the script.

args

[args]

(array of any, optional)

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

[files]

(array of string, optional)

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

[func]

(function, optional)

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

[injectImmediately]

(boolean, optional)

Whether the injection should be triggered in the target as soon as possible (but not necessarily prior to page load).

world

[world]

(ExecutionWorld, optional)