≡ storage API

• Permissions

• Events

• Types

• Properties

≡ Add-on developer resources

• Introduction to add-on development

• "Hello world" extension tutorial

• Developer community

• Sample extensions (Github)

• Using Promises

• Additional resources on DTN

≡ Guides

• Working with WebExtension events

• Working with message lists

• Working with vCard contacts

storage API

Hint

The storage 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.storage API to store, retrieve, and track changes to user data.

Note

The storage API is supported in content scripts from version 48.

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.

storage

storage

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

Note

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

Events

onChanged

– [Added in TB 45]

Fired when one or more items change.

Parameters for onChanged.addListener(listener)

listener(changes, areaName)

listener(changes, areaName)

A function that will be called when this event occurs.

Parameters passed to the listener function

changes

changes

(object)

Object mapping each key that changed to its corresponding StorageChange for that item.

areaName

areaName

(string)

The name of the storage area (“sync”, “local” or “managed”) the changes are for.

Required permissions

• storage

Types

StorageArea

– [Added in TB 45]

object

StorageAreaWithUsage

object

StorageChange

– [Added in TB 45]

object

newValue

[newValue]

(any, optional)

The new value of the item, if there is a new value.

oldValue

[oldValue]

(any, optional)

The old value of the item, if there was an old value.

Properties

local

Items in the local storage area are local to each machine.

Note

The storage API is supported in content scripts from version 48.

managed

Items in the managed storage area are set by administrators or native applications, and are read-only for the extension; trying to modify this namespace results in an error.

Note

Platform-specific storage backends, such as Windows registry keys, are not supported.

Note

Enforcement of extension-provided storage schemas is not supported.

Note

The onChanged event is not supported.

session

Items in the session storage area are kept in memory, and only until the either browser or extension is closed or reloaded.

sync

Items in the sync storage area are synced by the browser.

Note

Before version 79, storage quota limits are not enforced.