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
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
Block content on any page.
declarativeNetRequestFeedback
Read your browsing history.
declarativeNetRequestWithHostAccess
Allows blocking or upgrading requests to hosts for which host permissions have already been granted.
Functions
getAvailableStaticRuleCount()
– [Added in TB 113]
Returns the remaining number of static rules an extension can enable
Required permissions
getDisabledRuleIds(options)
– [Added in TB 128]
Returns the list of individual disabled static rules from a given static ruleset id.
Required permissions
getDynamicRules([filter])
– [Added in TB 113]
Returns the current set of dynamic rules for the extension.
Parameters
filter
An object to filter the set of dynamic rules for the extension.
Required permissions
getEnabledRulesets()
– [Added in TB 113]
Returns the ids for the current set of enabled static rulesets.
Required permissions
getSessionRules([filter])
– [Added in TB 113]
Returns the current set of session scoped rules for the extension.
Parameters
filter
An object to filter the set of session scoped rules for the extension.
Required permissions
isRegexSupported(regexOptions)
– [Added in TB 113]
Checks if the given regular expression will be supported as a ‘regexFilter’ rule condition.
Parameters
regexOptions
regex
The regular expresson to check.
isCaseSensitive
Whether the ‘regex’ specified is case sensitive.
requireCapturing
Whether the ‘regex’ specified requires capturing. Capturing is only required for redirect rules which specify a ‘regexSubstition’ action.
Return type (Promise)
_returns
isSupported
Whether the given regex is supported
reason
Specifies the reason why the regular expression is not supported. Only provided if ‘isSupported’ is false.
Required permissions
testMatchOutcome(request, [options])
– [Added in TB 113]
Checks if any of the extension’s declarativeNetRequest rules would match a hypothetical request.
Parameters
request
The details of the request to test.
type
The resource type of the hypothetical request.
url
The URL of the hypothetical request.
initiator
The initiator URL (if any) for the hypothetical request.
method
Standard HTTP method of the hypothetical request.
tabId
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
Required permissions
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
Required permissions
updateEnabledRulesets(updateRulesetOptions)
– [Added in TB 113]
Modifies the static rulesets enabled/disabled state.
Parameters
updateRulesetOptions
Required permissions
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
Required permissions
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
Required permissions
Types
GetRulesFilter
object
ruleIds
If specified, only rules with matching IDs are included.
MatchedRule
– [Added in TB 113]
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
csp_report
font
image
imageset
json
Note
The “json” property is supported from Thunderbird 135, but requests of this type are only available from Thunderbird 138.
main_frame
media
object
object_subrequest
other
ping
script
speculative
stylesheet
sub_frame
web_manifest
websocket
xml_dtd
xmlhttprequest
xslt
Rule
– [Added in TB 113]
object
action
The action to take if this rule is matched.
type
redirect
Describes how the redirect should be performed. Only valid when type is ‘redirect’.
extensionPath
Path relative to the extension directory. Should start with ‘/’.
regexSubstitution
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
Url transformations to perform.
url
The redirect url. Redirects to JavaScript urls are not allowed.
requestHeaders
The request headers to modify for the request. Only valid when type is ‘modifyHeaders’.
responseHeaders
The response headers to modify for the request. Only valid when type is ‘modifyHeaders’.
condition
The condition under which this rule is triggered.
domainType
excludedInitiatorDomains
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
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
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
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
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
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
Whether ‘urlFilter’ or ‘regexFilter’ is case-sensitive.
regexFilter
Regular expression to match against the network request url. Only one of ‘urlFilter’ or ‘regexFilter’ can be specified.
requestDomains
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
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
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
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
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
An id which uniquely identifies a rule. Mandatory and should be >= 1.
priority
Rule priority. Defaults to 1. When specified, should be >= 1
UnsupportedRegexReason
Describes the reason why a given regular expression isn’t supported.
URLTransform
– [Added in TB 113]
Describes the type of the Rule.action.redirect.transform property.
object
fragment
The new fragment for the request. Should be either empty, in which case the existing fragment is cleared; or should begin with ‘#’.
host
The new host name for the request.
password
The new password for the request.
path
The new path for the request. If empty, the existing path is cleared.
port
The new port for the request. If empty, the existing port is cleared.
query
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
Add, remove or replace query key-value pairs. Cannot be specified if ‘query’ is specified.
addOrReplaceParams
The list of query key-value pairs to be added or replaced.
removeParams
The list of query keys to be removed.
scheme
username
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.