declarativeNetRequest API

Hint

The declarativeNetRequest 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 declarativeNetRequest API to block or modify network requests by specifying declarative rules.

Manifest file properties

declarative_net_request

[declarative_net_request]

(object, optional)

rule_resources

rule_resources

(array of object)

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.

declarativeNetRequest

declarativeNetRequest

Block content on any page.

declarativeNetRequestFeedback

declarativeNetRequestFeedback

Read your browsing history.

declarativeNetRequestWithHostAccess

declarativeNetRequestWithHostAccess

Allows blocking or upgrading requests to hosts for which host permissions have already been granted.

Note

One of the permissions declarativeNetRequest or declarativeNetRequestWithHostAccess is required to use messenger.declarativeNetRequest.*.

Functions

getAvailableStaticRuleCount()

– [Added in TB 113]

Returns the remaining number of static rules an extension can enable

Return type (Promise)

_returns

integer

Required permissions

  • declarativeNetRequest

  • declarativeNetRequestWithHostAccess

getDisabledRuleIds(options)

– [Added in TB 128]

Returns the list of individual disabled static rules from a given static ruleset id.

Parameters

options

options

(object)

rulesetId

rulesetId

(string)

Return type (Promise)

_returns

array of integer

Required permissions

  • declarativeNetRequest

  • declarativeNetRequestWithHostAccess

getDynamicRules([filter])

– [Added in TB 113]

Returns the current set of dynamic rules for the extension.

Parameters

filter

[filter]

(GetRulesFilter, optional)

– [Added in TB 127]

An object to filter the set of dynamic rules for the extension.

Return type (Promise)

_returns

array of Rule

Required permissions

  • declarativeNetRequest

  • declarativeNetRequestWithHostAccess

getEnabledRulesets()

– [Added in TB 113]

Returns the ids for the current set of enabled static rulesets.

Return type (Promise)

_returns

array of string

Required permissions

  • declarativeNetRequest

  • declarativeNetRequestWithHostAccess

getSessionRules([filter])

– [Added in TB 113]

Returns the current set of session scoped rules for the extension.

Parameters

filter

[filter]

(GetRulesFilter, optional)

– [Added in TB 127]

An object to filter the set of session scoped rules for the extension.

Return type (Promise)

_returns

array of Rule

Required permissions

  • declarativeNetRequest

  • declarativeNetRequestWithHostAccess

isRegexSupported(regexOptions)

– [Added in TB 113]

Checks if the given regular expression will be supported as a ‘regexFilter’ rule condition.

Parameters

regexOptions

regexOptions

(object)

regex

regex

(string)

The regular expresson to check.

isCaseSensitive

[isCaseSensitive]

(boolean, optional)

Whether the ‘regex’ specified is case sensitive.

requireCapturing

[requireCapturing]

(boolean, optional)

Whether the ‘regex’ specified requires capturing. Capturing is only required for redirect rules which specify a ‘regexSubstition’ action.

Return type (Promise)

_returns

object

isSupported

isSupported

(boolean)

Whether the given regex is supported

reason

[reason]

Specifies the reason why the regular expression is not supported. Only provided if ‘isSupported’ is false.

Required permissions

  • declarativeNetRequest

  • declarativeNetRequestWithHostAccess

testMatchOutcome(request, [options])

– [Added in TB 113]

Checks if any of the extension’s declarativeNetRequest rules would match a hypothetical request.

Parameters

request

request

(object)

The details of the request to test.

type

type

The resource type of the hypothetical request.

url

url

(string)

The URL of the hypothetical request.

initiator

[initiator]

(string, optional)

The initiator URL (if any) for the hypothetical request.

method

[method]

(string, optional)

Standard HTTP method of the hypothetical request.

tabId

[tabId]

(integer, optional)

The ID of the tab in which the hypothetical request takes place. Does not need to correspond to a real tab ID. Default is -1, meaning that the request isn’t related to a tab.

options

[options]

(object, optional)

includeOtherExtensions

[includeOtherExtensions]

(boolean, optional)

Whether to account for rules from other installed extensions during rule evaluation.

Return type (Promise)

_returns

object

matchedRules

matchedRules

(array of MatchedRule)

The rules (if any) that match the hypothetical request.

Required permissions

  • declarativeNetRequest

  • declarativeNetRequestFeedback

  • declarativeNetRequestWithHostAccess

updateDynamicRules(options)

– [Added in TB 113]

Modifies the current set of dynamic rules for the extension. The rules with IDs listed in options.removeRuleIds are first removed, and then the rules given in options.addRules are added. These rules are persisted across browser sessions and extension updates.

Parameters

options

options

(object)

addRules

[addRules]

(array of Rule, optional)

Rules to add.

removeRuleIds

[removeRuleIds]

(array of integer, optional)

IDs of the rules to remove. Any invalid IDs will be ignored.

Required permissions

  • declarativeNetRequest

  • declarativeNetRequestWithHostAccess

updateEnabledRulesets(updateRulesetOptions)

– [Added in TB 113]

Modifies the static rulesets enabled/disabled state.

Parameters

updateRulesetOptions

updateRulesetOptions

(object)

disableRulesetIds

[disableRulesetIds]

(array of string, optional)

enableRulesetIds

[enableRulesetIds]

(array of string, optional)

Required permissions

  • declarativeNetRequest

  • declarativeNetRequestWithHostAccess

updateSessionRules(options)

– [Added in TB 113]

Modifies the current set of session scoped rules for the extension. The rules with IDs listed in options.removeRuleIds are first removed, and then the rules given in options.addRules are added. These rules are not persisted across sessions and are backed in memory.

Parameters

options

options

(object)

addRules

[addRules]

(array of Rule, optional)

Rules to add.

removeRuleIds

[removeRuleIds]

(array of integer, optional)

IDs of the rules to remove. Any invalid IDs will be ignored.

Required permissions

  • declarativeNetRequest

  • declarativeNetRequestWithHostAccess

updateStaticRules(options)

– [Added in TB 128]

Modified individual static rules enabled/disabled state. Changes to rules belonging to a disabled ruleset will take effect when the ruleset becomes enabled.

Parameters

options

options

(object)

rulesetId

rulesetId

(string)

disableRuleIds

[disableRuleIds]

(array of integer, optional)

enableRuleIds

[enableRuleIds]

(array of integer, optional)

Required permissions

  • declarativeNetRequest

  • declarativeNetRequestWithHostAccess

Types

GetRulesFilter

object

ruleIds

[ruleIds]

(array of integer, optional)

If specified, only rules with matching IDs are included.

MatchedRule

– [Added in TB 113]

object

ruleId

ruleId

(integer)

A matching rule’s ID.

rulesetId

rulesetId

(string)

ID of the Ruleset this rule belongs to.

extensionId

[extensionId]

(string, optional)

ID of the extension, if this rule belongs to a different extension.

ResourceType

– [Added in TB 113]

How the requested resource will be used. Comparable to the webRequest.ResourceType type. object_subrequest is unsupported.

string

Supported values:

beacon

beacon

csp_report

csp_report

font

font

image

image

imageset

imageset

json

json

– [Added in TB 138]

Note

The “json” property is supported from Thunderbird 135, but requests of this type are only available from Thunderbird 138.

main_frame

main_frame

media

media

object

object

object_subrequest

object_subrequest

other

other

ping

ping

script

script

speculative

speculative

stylesheet

stylesheet

sub_frame

sub_frame

web_manifest

web_manifest

websocket

websocket

xml_dtd

xml_dtd

xmlhttprequest

xmlhttprequest

xslt

xslt

Rule

– [Added in TB 113]

object

action

action

(object)

The action to take if this rule is matched.

type

type

(string)

Supported values:

allow

allow

allowAllRequests

allowAllRequests

block

block

modifyHeaders

modifyHeaders

redirect

redirect

upgradeScheme

upgradeScheme

redirect

[redirect]

(object, optional)

Describes how the redirect should be performed. Only valid when type is ‘redirect’.

extensionPath

[extensionPath]

(string, optional)

Path relative to the extension directory. Should start with ‘/’.

regexSubstitution

[regexSubstitution]

(string, optional)

Substitution pattern for rules which specify a ‘regexFilter’. The first match of regexFilter within the url will be replaced with this pattern. Within regexSubstitution, backslash-escaped digits (\1 to \9) can be used to insert the corresponding capture groups. \0 refers to the entire matching text.

transform

[transform]

(URLTransform, optional)

Url transformations to perform.

url

[url]

(string, optional)

The redirect url. Redirects to JavaScript urls are not allowed.

requestHeaders

[requestHeaders]

(array of object, optional)

The request headers to modify for the request. Only valid when type is ‘modifyHeaders’.

responseHeaders

[responseHeaders]

(array of object, optional)

The response headers to modify for the request. Only valid when type is ‘modifyHeaders’.

condition

condition

(object)

The condition under which this rule is triggered.

domainType

[domainType]

(string, optional)

Specifies whether the network request is first-party or third-party to the domain from which it originated. If omitted, all requests are matched.

Supported values:

firstParty

firstParty

thirdParty

thirdParty

excludedInitiatorDomains

[excludedInitiatorDomains]

(array of string, optional)

The rule will not match network requests originating from the list of ‘initiatorDomains’. If the list is empty or omitted, no domains are excluded. This takes precedence over ‘initiatorDomains’.

excludedRequestDomains

[excludedRequestDomains]

(array of string, optional)

The rule will not match network requests when the domains matches one from the list of ‘excludedRequestDomains’. If the list is empty or omitted, no domains are excluded. This takes precedence over ‘requestDomains’.

excludedRequestMethods

[excludedRequestMethods]

(array of string, optional)

List of request methods which the rule won’t match. Cannot be specified if ‘requestMethods’ is specified. If neither of them is specified, all request methods are matched.

excludedResourceTypes

[excludedResourceTypes]

(array of ResourceType, optional)

List of resource types which the rule won’t match. Cannot be specified if ‘resourceTypes’ is specified. If neither of them is specified, all resource types except ‘main_frame’ are matched.

excludedTabIds

[excludedTabIds]

(array of integer, optional)

List of tabIds which the rule should not match. An ID of -1 excludes requests which don’t originate from a tab. Only supported for session-scoped rules.

initiatorDomains

[initiatorDomains]

(array of string, optional)

The rule will only match network requests originating from the list of ‘initiatorDomains’. If the list is omitted, the rule is applied to requests from all domains.

isUrlFilterCaseSensitive

[isUrlFilterCaseSensitive]

(boolean, optional)

Whether ‘urlFilter’ or ‘regexFilter’ is case-sensitive.

regexFilter

[regexFilter]

(string, optional)

Regular expression to match against the network request url. Only one of ‘urlFilter’ or ‘regexFilter’ can be specified.

requestDomains

[requestDomains]

(array of string, optional)

The rule will only match network requests when the domain matches one from the list of ‘requestDomains’. If the list is omitted, the rule is applied to requests from all domains.

requestMethods

[requestMethods]

(array of string, optional)

List of HTTP request methods which the rule can match. Should be a lower-case method such as ‘connect’, ‘delete’, ‘get’, ‘head’, ‘options’, ‘patch’, ‘post’, ‘put’.’

resourceTypes

[resourceTypes]

(array of ResourceType, optional)

List of resource types which the rule can match. When the rule action is ‘allowAllRequests’, this must be specified and may only contain ‘main_frame’ or ‘sub_frame’. Cannot be specified if ‘excludedResourceTypes’ is specified. If neither of them is specified, all resource types except ‘main_frame’ are matched.

tabIds

[tabIds]

(array of integer, optional)

List of tabIds which the rule should match. An ID of -1 matches requests which don’t originate from a tab. Only supported for session-scoped rules.

urlFilter

[urlFilter]

(string, optional)

TODO: link to doc explaining supported pattern. The pattern which is matched against the network request url. Only one of ‘urlFilter’ or ‘regexFilter’ can be specified.

id

id

(integer)

An id which uniquely identifies a rule. Mandatory and should be >= 1.

priority

[priority]

(integer, optional)

Rule priority. Defaults to 1. When specified, should be >= 1

UnsupportedRegexReason

Describes the reason why a given regular expression isn’t supported.

string

Supported values:

memoryLimitExceeded

memoryLimitExceeded

syntaxError

syntaxError

URLTransform

– [Added in TB 113]

Describes the type of the Rule.action.redirect.transform property.

object

fragment

[fragment]

(string, optional)

The new fragment for the request. Should be either empty, in which case the existing fragment is cleared; or should begin with ‘#’.

host

[host]

(string, optional)

The new host name for the request.

password

[password]

(string, optional)

The new password for the request.

path

[path]

(string, optional)

The new path for the request. If empty, the existing path is cleared.

port

[port]

(string, optional)

The new port for the request. If empty, the existing port is cleared.

query

[query]

(string, optional)

The new query for the request. Should be either empty, in which case the existing query is cleared; or should begin with ‘?’. Cannot be specified if ‘queryTransform’ is specified.

queryTransform

[queryTransform]

(object, optional)

Add, remove or replace query key-value pairs. Cannot be specified if ‘query’ is specified.

addOrReplaceParams

[addOrReplaceParams]

(array of object, optional)

The list of query key-value pairs to be added or replaced.

removeParams

[removeParams]

(array of string, optional)

The list of query keys to be removed.

scheme

[scheme]

(string, optional)

The new scheme for the request.

Supported values:

http

http

https

https

moz-extension

moz-extension

username

[username]

(string, optional)

The new username for the request.

Properties

DYNAMIC_RULESET_ID

Ruleset ID for the dynamic rules added by the extension.

GUARANTEED_MINIMUM_STATIC_RULES

The minimum number of static rules guaranteed to an extension across its enabled static rulesets. Any rules above this limit will count towards the global static rule limit.

MAX_NUMBER_OF_DISABLED_STATIC_RULES

The maximum number of static rules that can be disabled on each static ruleset.

MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES

Deprecated property returning the maximum number of dynamic and session rules an extension can add, replaced by MAX_NUMBER_OF_DYNAMIC_RULES/MAX_NUMBER_OF_SESSION_RULES.

Note

Deprecated in Thunderbird 128. Use MAX_NUMBER_OF_DYNAMIC_RULES and MAX_NUMBER_OF_SESSION_RULES instead.

MAX_NUMBER_OF_DYNAMIC_RULES

The maximum number of dynamic session rules an extension can add.

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

The maximum number of static Rulesets an extension can enable at any one time.

MAX_NUMBER_OF_REGEX_RULES

The maximum number of regular expression rules that an extension can add. This limit is evaluated separately for the set of session rules, dynamic rules and those specified in the rule_resources file.

MAX_NUMBER_OF_SESSION_RULES

The maximum number of dynamic session rules an extension can add.

MAX_NUMBER_OF_STATIC_RULESETS

The maximum number of static Rulesets an extension can specify as part of the rule_resources manifest key.

SESSION_RULESET_ID

Ruleset ID for the session-scoped rules added by the extension.