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

create(parent, childName)

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

Parameters

parent

childName

(string)

Return type (Promise)

Required permissions

  • accountsRead

  • accountsFolders

rename(folder, newName)

Renames a folder.

Parameters

folder

newName

(string)

Return type (Promise)

Required permissions

  • accountsRead

  • accountsFolders

move(sourceFolder, destination)

– [Added in TB 91]

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

Parameters

sourceFolder

destination

Return type (Promise)

Required permissions

  • accountsRead

  • accountsFolders

copy(sourceFolder, destination)

– [Added in TB 91]

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

Parameters

sourceFolder

destination

Return type (Promise)

Required permissions

  • accountsRead

  • accountsFolders

delete(folder)

Deletes a folder.

Parameters

folder

Required permissions

  • accountsRead

  • accountsFolders

  • messagesDelete

getFolderInfo(folder)

– [Added in TB 91]

Get additional information about a mail 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(folderOrAccount, [includeSubFolders])

– [Added in TB 91]

Get the subfolders of the specified folder or account.

Parameters

folderOrAccount

[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

Events

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

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

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

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

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

Types

MailFolder

An object describing a mail folder, as returned for example by the getParentFolders(folder, [includeSubFolders]) or getSubFolders(folderOrAccount, [includeSubFolders]) methods, or part of a MailAccount object, which is returned for example by the list([includeFolders]) and get(accountId, [includeFolders]) methods. The subFolders property is only included if requested.

object

accountId

(string)

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(folderOrAccount, [includeSubFolders]) to obtain hierarchy information.

[name]

(string, optional)

The human-friendly name of this folder.

[subFolders]

(array of MailFolder, optional)

– [Added in TB 74]

Subfolders are only included if requested.

[type]

(string, optional)

The type of folder, for several common types.

Supported values:

inbox

drafts

sent

trash

templates

archives

junk

outbox

MailFolderInfo

– [Added in TB 91]

An object containing additional information about a mail folder.

object

[favorite]

(boolean, optional)

Whether this folder is a favorite folder.

[totalMessageCount]

(integer, optional)

Number of messages in this folder.

[unreadMessageCount]

(integer, optional)

Number of unread messages in this folder.