folders API

The folders API first appeared in Thunderbird 68 as a part of the accounts API. It was later moved here.

Permissions

accountsFolders

Create, rename, or delete your mail account folders

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

Return type (Promise)

Required permissions

  • accountsRead

  • accountsFolders

create(destination, childName)

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

Parameters

destination

childName

(string)

Return type (Promise)

Required permissions

  • accountsRead

  • accountsFolders

delete(folder)

Deletes a folder.

Parameters

folder

Required permissions

  • accountsRead

  • accountsFolders

  • messagesDelete

get(folder, [includeSubFolders])

– [Added in TB 121]

Returns the specified folder.

Parameters

folder

[includeSubFolders]

(boolean, optional)

Specifies whether the returned MailFolder object should include all its nested subfolders . Defaults to true.

Return type (Promise)

Required permissions

  • accountsRead

getFolderCapabilities(folder)

– [Added in TB 121]

Get capability information about a folder.

Parameters

folder

Required permissions

  • accountsRead

getFolderInfo(folder)

– [Added in TB 91]

Get additional information about a folder.

Parameters

folder

Return type (Promise)

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]

(boolean, optional)

Specifies whether the returned MailFolder object for each parent folder should include its nested subfolders . Defaults to false.

Return type (Promise)

array of MailFolder

Required permissions

  • accountsRead

getSubFolders(folder, [includeSubFolders])

– [Added in TB 91]

Get the subfolders of the specified folder or account.

Parameters

[includeSubFolders]

(boolean, optional)

Specifies whether the returned MailFolder object for each direct subfolder should also include all its nested subfolders . Defaults to true.

Return type (Promise)

array of MailFolder

Required permissions

  • accountsRead

markAsRead(folder)

– [Added in TB 121]

Marks all messages in a folder as read.

Parameters

folder

Required permissions

  • accountsRead

  • accountsFolders

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

Return type (Promise)

Required permissions

  • accountsRead

  • accountsFolders

query([queryInfo])

– [Added in TB 121]

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

Parameters

[queryInfo]

(object, optional)

[accountId]

(MailAccountId, optional)

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

[canAddMessages]

(boolean, optional)

Whether the folder supports adding new messages, or not.

[canAddSubfolders]

(boolean, optional)

Whether the folder supports adding new subfolders, or not.

[canBeDeleted]

(boolean, optional)

Whether the folder can be deleted, or not.

[canBeRenamed]

(boolean, optional)

Whether the folder can be renamed, or not.

[canDeleteMessages]

(boolean, optional)

Whether the folder supports deleting messages, or not.

[folderId]

(MailFolderId, optional)

Limits the search to the folder with the specified id.

[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]

(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]

(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]

(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]

(boolean, optional)

Whether the folder is a favorite folder, or not.

[isRoot]

(boolean, optional)

Whether the folder is a root folder, or not.

[isVirtual]

(boolean, optional)

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

[limit]

(integer, optional)

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

[name]

(RegularExpression or string, optional)

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

[path]

(RegularExpression or string, optional)

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

[recent]

(boolean, optional)

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

[specialUse]

(array of MailFolderSpecialUse, optional)

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

[type]

(MailFolderSpecialUse, optional)

Deprecated. Match only folders with the specified special use.

Return type (Promise)

array of MailFolder

Required permissions

  • accountsRead

rename(folder, newName)

Renames a folder.

Parameters

folder

newName

(string)

Return type (Promise)

Required permissions

  • accountsRead

  • accountsFolders

update(folder, updateProperties)

– [Added in TB 121]

Updates properties of a folder.

Parameters

folder

updateProperties

(object)

The properties to update.

[isFavorite]

(boolean, optional)

Sets or clears the favorite status.

Required permissions

  • accountsRead

  • accountsFolders

Events

onCopied

– [Added in TB 91]

Fired when a folder has been copied.

Parameters for onCopied.addListener(listener)

listener(originalFolder, copiedFolder)

A function that will be called when this event occurs.

Parameters passed to the listener function

originalFolder

copiedFolder

Required permissions

  • accountsRead

onCreated

– [Added in TB 91]

Fired when a folder has been created.

Parameters for onCreated.addListener(listener)

listener(createdFolder)

A function that will be called when this event occurs.

Parameters passed to the listener function

createdFolder

Required permissions

  • accountsRead

onDeleted

– [Added in TB 91]

Fired when a folder has been deleted.

Parameters for onDeleted.addListener(listener)

listener(deletedFolder)

A function that will be called when this event occurs.

Parameters passed to the listener function

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)

A function that will be called when this event occurs.

Parameters passed to the listener function

folder

folderInfo

Required permissions

  • accountsRead

onMoved

– [Added in TB 91]

Fired when a folder has been moved.

Parameters for onMoved.addListener(listener)

listener(originalFolder, movedFolder)

A function that will be called when this event occurs.

Parameters passed to the listener function

originalFolder

movedFolder

Required permissions

  • accountsRead

onRenamed

– [Added in TB 91]

Fired when a folder has been renamed.

Parameters for onRenamed.addListener(listener)

listener(originalFolder, renamedFolder)

A function that will be called when this event occurs.

Parameters passed to the listener function

originalFolder

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)

A function that will be called when this event occurs.

Parameters passed to the listener function

originalFolder

updatedFolder

Required permissions

  • accountsRead

Types

MailFolder

An object describing a folder. The subFolders property is only included if requested.

object

accountId

The id of the account this folder belongs to.

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.

[id]

(MailFolderId, optional)

An identifier for the folder.

[isFavorite]

(boolean, optional)

– [Added in TB 121]

Whether this folder is a favorite folder.

[isRoot]

(boolean, optional)

– [Added in TB 121]

Whether this folder is a root folder.

[isVirtual]

(boolean, optional)

– [Added in TB 121]

Whether this folder is a virtual search folder.

[name]

(string, optional)

The human-friendly name of this folder.

[specialUse]

(array of MailFolderSpecialUse, optional)

– [Added in TB 121]

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

[subFolders]

(array of MailFolder, optional)

– [Added in TB 74]

Subfolders are only included if requested. They will be returned in the same order as used in Thunderbird’s folder pane.

[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]

(boolean, optional)

Whether this folder supports adding new messages.

[canAddSubfolders]

(boolean, optional)

Whether this folder supports adding new subfolders.

[canBeDeleted]

(boolean, optional)

Whether this folder can be deleted.

[canBeRenamed]

(boolean, optional)

Whether this folder can be renamed.

[canDeleteMessages]

(boolean, optional)

Whether this folder supports deleting messages.

MailFolderId

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]

(boolean, optional)

Deprecated. This information is now available in MailFolder.

[lastUsed]

(Date, optional)

– [Added in TB 121]

Date the folder was last used (precision: seconds).

[newMessageCount]

(integer, optional)

– [Added in TB 121]

Number of new messages in this folder.

[quota]

(array of MailFolderQuota, optional)

– [Added in TB 121]

Quota information, if available.

[totalMessageCount]

(integer, optional)

Number of messages in this folder.

[unreadMessageCount]

(integer, optional)

Number of unread messages in this folder.

MailFolderQuota

– [Added in TB 121]

An object containing quota information.

object

limit

(integer)

The maximum available quota.

type

(string)

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

Supported values:

STORAGE

MESSAGE

unused

(integer)

The currently unused quota.

used

(integer)

The currently used quota.

MailFolderSpecialUse

– [Added in TB 121]

Supported values for the special use of a folder.

string

Supported values:

inbox

drafts

sent

trash

templates

archives

junk

outbox

QueryRange

An object defining a range.

object

[max]

(integer, optional)

The maximum value required to match the query.

[min]

(integer, optional)

The minimum value required to match the query.

RegularExpression

object

regexp

(string)

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

[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. Controled by the mail.folder_widget.max_recent preference.