folders API
The folders API first appeared in Thunderbird 68 as a part of the accounts API. It was later moved here.
Permissions
Create, rename, or delete your mail account folders
Functions
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.
Return type (Promise)
Required permissions
create(parent, childName)
Creates a new subfolder in the specified folder or at the root of the specified account.
Return type (Promise)
Required permissions
delete(folder)
Deletes a folder.
Parameters
Required permissions
getFolderInfo(folder)
– [Added in TB 91]
Get additional information about a mail folder.
Parameters
Return type (Promise)
Required permissions
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
[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
getSubFolders(folderOrAccount, [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
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.
Return type (Promise)
Required permissions
rename(folder, newName)
Renames a folder.
Return type (Promise)
Required permissions
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.
Required permissions
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
Required permissions
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
Required permissions
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.
Required permissions
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.
Required permissions
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.
Required permissions
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 are only included if requested. They will be returned in the same order as used in Thunderbird’s folder pane.
[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.