folders API

The folders API allows to access and manage the user’s message folders.

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.

accountsFolders

accountsFolders

Create, rename, or delete your mail account folders.

accountsRead

accountsRead

See your mail accounts, their identities and their folders.

messagesDelete

messagesDelete

Permanently delete your email messages.

Note

The permission accountsRead is required to use messenger.folders.*.

Functions

copy(source, destination)

– [Added in TB 91]

Copies the given source folder into the given destination folder. Throws if the destination already contains a folder with the name of the source folder.

Parameters

source

destination

destination

Return type (Promise)

_returns

Required permissions

  • accountsFolders

  • accountsRead

create(destination, childName)

– [Added in TB 68]

Creates a new subfolder in the specified folder, or at the root of the specified account.

Parameters

destination

destination

childName

childName

(string)

Return type (Promise)

_returns

– [Added in TB 91]

Required permissions

  • accountsFolders

  • accountsRead

delete(folder)

– [Added in TB 68]

Deletes a folder.

Parameters

folder

Required permissions

  • accountsFolders

  • accountsRead

  • messagesDelete

get(folderId, [includeSubFolders])

– [Added in TB 121]

Returns the specified folder.

Parameters

folderId

folderId

includeSubFolders

[includeSubFolders]

(boolean, optional)

Specifies whether the returned MailFolder should populate its subFolders property and include all its (nested!) subfolders. Defaults to true.

Return type (Promise)

_returns

Required permissions

  • accountsRead

getFolderCapabilities(folder)

– [Added in TB 121]

Get capability information about a folder.

Parameters

folder

Return type (Promise)

_returns

Required permissions

  • accountsRead

getFolderInfo(folder)

– [Added in TB 91]

Get additional information about a folder.

Parameters

folder

Return type (Promise)

_returns

Required permissions

  • accountsRead

getParentFolders(folder, [includeSubFolders])

– [Added in TB 91]

Get all parent folders as a flat ordered array. The first array entry is the direct parent.

Parameters

folder

includeSubFolders

[includeSubFolders]

(boolean, optional)

Specifies whether each returned parent MailFolder should populate its subFolders property and include all its (nested!) subfolders. Defaults to false.

Return type (Promise)

_returns

array of MailFolder

Required permissions

  • accountsRead

getSubFolders(folder, [includeSubFolders])

– [Added in TB 91]

Get the subfolders of the specified folder or account.

Parameters

folder

includeSubFolders

[includeSubFolders]

(boolean, optional)

Specifies whether each returned direct child MailFolder should populate its subFolders property and include all its (nested!) subfolders. Defaults to true.

Return type (Promise)

_returns

array of MailFolder

Required permissions

  • accountsRead

getTagFolder(key)

– [Added in TB 127]

Get one of the special virtual tag folders, which are virtual search folders and group messages from all mail accounts based on their tags. Throws if the requested folder does not exist.

Parameters

key

key

(string)

The tag key of the requested folder. See list() for the available tags. Throws when specifying an invalid tag key.

Return type (Promise)

_returns

Required permissions

  • accountsRead

getUnifiedFolder(type, [includeSubFolders])

– [Added in TB 127]

Get one of the special unified mailbox folders, which are virtual search folders and return the content from all mail accounts. Throws if the requested folder does not exist.

Parameters

type

type

(string)

The requested unified mailbox folder type.

Supported values:

archives

archives

drafts

drafts

inbox

inbox

junk

junk

sent

sent

templates

templates

trash

trash

includeSubFolders

[includeSubFolders]

(boolean, optional)

Specifies whether the returned MailFolder should populate its subFolders property and include all its (nested!) subfolders. Defaults to false.

Return type (Promise)

_returns

Required permissions

  • accountsRead

markAsRead(folder)

– [Added in TB 121]

Marks all messages in a folder as read.

Parameters

folder

Required permissions

  • accountsFolders

  • accountsRead

move(source, destination)

– [Added in TB 91]

Moves the given source folder into the given destination folder. Throws if the destination already contains a folder with the name of the source folder.

Parameters

source

destination

destination

Return type (Promise)

_returns

Required permissions

  • accountsFolders

  • accountsRead

query([queryInfo])

– [Added in TB 121]

Gets folders that match the specified properties, or all folders if no properties are specified.

Parameters

queryInfo

[queryInfo]

(object, optional)

accountId

[accountId]

(MailAccountId, optional)

Limits the search to folders of the account with the specified id.

canAddMessages

[canAddMessages]

(boolean, optional)

Whether the folder supports adding new messages, or not.

canAddSubfolders

[canAddSubfolders]

(boolean, optional)

Whether the folder supports adding new subfolders, or not.

canBeDeleted

[canBeDeleted]

(boolean, optional)

Whether the folder can be deleted, or not.

canBeRenamed

[canBeRenamed]

(boolean, optional)

Whether the folder can be renamed, or not.

canDeleteMessages

[canDeleteMessages]

(boolean, optional)

Whether the folder supports deleting messages, or not.

folderId

[folderId]

(MailFolderId, optional)

Limits the search to the folder with the specified id.

hasMessages

[hasMessages]

(boolean or QueryRange, optional)

Whether the folder (excluding subfolders) contains messages, or not. Supports to specify a QueryRange (min/max) instead of a simple boolean value (none/some).

hasNewMessages

[hasNewMessages]

(boolean or QueryRange, optional)

Whether the folder (excluding subfolders) contains new messages, or not. Supports to specify a QueryRange (min/max) instead of a simple boolean value (none/some).

hasSubFolders

[hasSubFolders]

(boolean or QueryRange, optional)

Whether the folder has subfolders, or not. Supports to specify a QueryRange (min/max) instead of a simple boolean value (none/some).

hasUnreadMessages

[hasUnreadMessages]

(boolean or QueryRange, optional)

Whether the folder (excluding subfolders) contains unread messages, or not. Supports to specify a QueryRange (min/max) instead of a simple boolean value (none/some).

isFavorite

[isFavorite]

(boolean, optional)

Whether the folder is a favorite folder, or not.

isRoot

[isRoot]

(boolean, optional)

Whether the folder is a root folder, or not.

isTag

[isTag]

(boolean, optional)

– [Added in TB 127]

Whether the folder is a virtual tag folder, or not. Virtual tag folders are always skipped, unless this property is set to true

isUnified

[isUnified]

(boolean, optional)

– [Added in TB 127]

Whether the folder is a unified mailbox folder, or not. Unified mailbox folders are always skipped, unless this property is set to true

isVirtual

[isVirtual]

(boolean, optional)

Whether the folder is a virtual search folder, or not.

lastUsed

[lastUsed]

(QueryDateRange, optional)

– [Added in TB 137]

Date the folder was last used (folder was accessed, user moved or copied messages into the folder or folder received new messages).

lastUsedAsDestination

[lastUsedAsDestination]

(QueryDateRange, optional)

– [Added in TB 137]

Date the folder was last used as a destination (user moved or copied messages into the folder).

limit

[limit]

(integer, optional)

– [Added in TB 122]

Limits the number of returned folders. If used together with recent, supports being set to DEFAULT_MOST_RECENT_LIMIT

name

[name]

(RegularExpression or string, optional)

Return only folders whose name is matched by the provided string or regular expression.

path

[path]

(RegularExpression or string, optional)

Return only folders whose path is matched by the provided string or regular expression.

recent

[recent]

(boolean, optional) Deprecated.

Whether the folder (excluding subfolders) has been used within the last month, or not. The returned folders will be sorted by lastUsed.

sort

[sort]

(string, optional)

– [Added in TB 137]

The sort order of the returned folders. If not specified, folders will be sorted by path. Sorting by name is case-insensitive.

Supported values:

lastUsed

lastUsed

lastUsedAsDestination

lastUsedAsDestination

name

name

path

path

specialUse

[specialUse]

(array of MailFolderSpecialUse, optional)

Match only folders with the specified special use (folders have to match all specified uses).

type

[type]

(MailFolderSpecialUse, optional)

Deprecated. Match only folders with the specified special use.

Return type (Promise)

_returns

array of MailFolder

Required permissions

  • accountsRead

rename(folder, newName)

– [Added in TB 68]

Renames a folder.

Parameters

folder

newName

newName

(string)

Return type (Promise)

_returns

– [Added in TB 91]

Required permissions

  • accountsFolders

  • accountsRead

update(folder, updateProperties)

– [Added in TB 121]

Updates properties of a folder.

Parameters

folder

updateProperties

updateProperties

(object)

The properties to update.

isFavorite

[isFavorite]

(boolean, optional)

Sets or clears the favorite status.

Required permissions

  • accountsFolders

  • accountsRead

Events

onCopied

– [Added in TB 91]

Fired when a folder has been copied.

Parameters for onCopied.addListener(listener)

listener(originalFolder, copiedFolder)

listener(originalFolder, copiedFolder)

A function that will be called when this event occurs.

Parameters passed to the listener function

originalFolder

originalFolder

copiedFolder

copiedFolder

Required permissions

  • accountsRead

onCreated

– [Added in TB 91]

Fired when a folder has been created.

Parameters for onCreated.addListener(listener)

listener(createdFolder)

listener(createdFolder)

A function that will be called when this event occurs.

Parameters passed to the listener function

createdFolder

createdFolder

Required permissions

  • accountsRead

onDeleted

– [Added in TB 91]

Fired when a folder has been deleted.

Parameters for onDeleted.addListener(listener)

listener(deletedFolder)

listener(deletedFolder)

A function that will be called when this event occurs.

Parameters passed to the listener function

deletedFolder

deletedFolder

Required permissions

  • accountsRead

onFolderInfoChanged

– [Added in TB 91]

Fired when certain information of a folder have changed. Bursts of message count changes are collapsed to a single event.

Parameters for onFolderInfoChanged.addListener(listener)

listener(folder, folderInfo)

listener(folder, folderInfo)

A function that will be called when this event occurs.

Parameters passed to the listener function

folder

folder

folderInfo

folderInfo

Required permissions

  • accountsRead

onMoved

– [Added in TB 91]

Fired when a folder has been moved.

Parameters for onMoved.addListener(listener)

listener(originalFolder, movedFolder)

listener(originalFolder, movedFolder)

A function that will be called when this event occurs.

Parameters passed to the listener function

originalFolder

originalFolder

movedFolder

movedFolder

Required permissions

  • accountsRead

onRenamed

– [Added in TB 91]

Fired when a folder has been renamed.

Parameters for onRenamed.addListener(listener)

listener(originalFolder, renamedFolder)

listener(originalFolder, renamedFolder)

A function that will be called when this event occurs.

Parameters passed to the listener function

originalFolder

originalFolder

renamedFolder

renamedFolder

Required permissions

  • accountsRead

onUpdated

– [Added in TB 121]

Fired when properties of a folder have changed (specialUse and isFavorite).

Parameters for onUpdated.addListener(listener)

listener(originalFolder, updatedFolder)

listener(originalFolder, updatedFolder)

A function that will be called when this event occurs.

Parameters passed to the listener function

originalFolder

originalFolder

updatedFolder

updatedFolder

Required permissions

  • accountsRead

Types

MailFolder

– [Added in TB 68]

An object describing a folder.

object

path

path

(string)

Path to this folder in the account. Although paths look predictable, never guess a folder’s path, as there are a number of reasons why it may not be what you think it is. Use getParentFolders(folder, [includeSubFolders]) or getSubFolders(folder, [includeSubFolders]) to obtain hierarchy information.

accountId

[accountId]

(MailAccountId, optional)

The id of the account this folder belongs to.

id

[id]

(MailFolderId, optional)

– [Added in TB 121]

An identifier for the folder.

isFavorite

[isFavorite]

(boolean, optional)

– [Added in TB 121]

Whether this folder is a favorite folder.

isRoot

[isRoot]

(boolean, optional)

– [Added in TB 121]

Whether this folder is a root folder.

isTag

[isTag]

(boolean, optional)

– [Added in TB 127]

Whether this folder is a virtual tag folder.

isUnified

[isUnified]

(boolean, optional)

– [Added in TB 127]

Whether this folder is a unified mailbox folder.

isVirtual

[isVirtual]

(boolean, optional)

– [Added in TB 121]

Whether this folder is a virtual search folder.

name

[name]

(string, optional)

The human-friendly name of this folder.

specialUse

[specialUse]

(array of MailFolderSpecialUse, optional)

– [Added in TB 121]

The special use of this folder. A folder can have multiple special uses.

subFolders

[subFolders]

(array of MailFolder, optional)

– [Added in TB 74]

Subfolders of this folder. This property is optional and only present if the inclusion of subfolders had been requested. The folders will be returned in the same order as used in Thunderbird’s folder pane.

type

[type]

(MailFolderSpecialUse, optional)

Deprecated. Was used to represent the type of this folder.

MailFolderCapabilities

– [Added in TB 121]

An object containing capability information about a folder.

object

canAddMessages

[canAddMessages]

(boolean, optional)

Whether this folder supports adding new messages.

canAddSubfolders

[canAddSubfolders]

(boolean, optional)

Whether this folder supports adding new subfolders.

canBeDeleted

[canBeDeleted]

(boolean, optional)

Whether this folder can be deleted.

canBeRenamed

[canBeRenamed]

(boolean, optional)

Whether this folder can be renamed.

canDeleteMessages

[canDeleteMessages]

(boolean, optional)

Whether this folder supports deleting messages.

MailFolderId

– [Added in TB 121]

A unique id representing a MailFolder throughout a session. Renaming or moving a folder will invalidate its id.

string

MailFolderInfo

– [Added in TB 91]

An object containing additional information about a folder.

object

favorite

[favorite]

(boolean, optional)

Deprecated. This information is now available in MailFolder.

lastUsed

[lastUsed]

(Date, optional)

– [Added in TB 121]

Date the folder was last used. It is updated every time the folder was accessed, when the user moved or copied messages into the folder and when the folder received new messages. (precision: seconds).

lastUsedAsDestination

[lastUsedAsDestination]

(Date, optional)

– [Added in TB 137]

Date the folder was last used as a destination. It is updated every time the user moved or copied messages into the folder. (precision: seconds).

newMessageCount

[newMessageCount]

(integer, optional)

– [Added in TB 121]

Number of new messages in this folder.

quota

[quota]

(array of MailFolderQuota, optional)

– [Added in TB 121]

Quota information, if available.

totalMessageCount

[totalMessageCount]

(integer, optional)

Number of messages in this folder.

unreadMessageCount

[unreadMessageCount]

(integer, optional)

Number of unread messages in this folder.

MailFolderQuota

– [Added in TB 121]

An object containing quota information.

object

limit

limit

(integer)

The maximum available quota.

type

type

(string)

The type of the quota as defined by RFC 2087. A STORAGE quota is constraining the available storage in bytes, a MESSAGE quota is constraining the number of storable messages.

Supported values:

MESSAGE

MESSAGE

STORAGE

STORAGE

unused

unused

(integer)

The currently unused quota.

used

used

(integer)

The currently used quota.

MailFolderSpecialUse

– [Added in TB 121]

Supported values for the special use of a folder.

string

Supported values:

archives

archives

drafts

drafts

inbox

inbox

junk

junk

outbox

outbox

sent

sent

templates

templates

trash

trash

QueryDateRange

– [Added in TB 137]

An object defining a range for a date value to be used in queries.

object

recent

recent

(boolean)

Whether the date must be considered to be recent by Thunderbird (within the last month) or not, to match the query.

or

object

after

[after]

(Date, optional)

The minimum date required to match the query.

before

[before]

(Date, optional)

The maximum date required to match the query.

QueryRange

– [Added in TB 121]

An object defining a range for an integer value to be used in queries.

object

max

[max]

(integer, optional)

The maximum value required to match the query.

min

[min]

(integer, optional)

The minimum value required to match the query.

RegularExpression

– [Added in TB 121]

object

regexp

regexp

(string)

A regular expression, for example ^Projects \d{4}$.

flags

[flags]

(string, optional)

Supported RegExp flags: i = case insensitive, and/or one of u = unicode support or v = extended unicode support

Properties

DEFAULT_MOST_RECENT_LIMIT

The number of most recent folders used in Thunderbird’s UI. Controlled by the mail.folder_widget.max_recent preference.