folders API
The folders API allows to manage the user’s message folders.
Permissions
Create, rename, or delete your mail account folders
Functions
copy(sourceFolderId, destinationFolderId)
– [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.
Return type (Promise)
Required permissions
create(folderId, childName)
Creates a new subfolder in the specified folder.
Return type (Promise)
Required permissions
delete(folderId)
Deletes a folder.
Parameters
Required permissions
get(folderId, [includeSubFolders])
– [Added in TB 121]
Returns the specified folder.
Parameters
[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)
Required permissions
getFolderCapabilities(folderId)
– [Added in TB 121]
Get capability information about a folder.
Parameters
Return type (Promise)
Required permissions
getFolderInfo(folderId)
– [Added in TB 91]
Get additional information about a folder.
Parameters
Return type (Promise)
Required permissions
getParentFolders(folderId, [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 each returned parent MailFolder should populate its subFolders property and include all its (nested!) subfolders. Defaults to false.
Return type (Promise)
array of MailFolder
Required permissions
getSubFolders(folderId, [includeSubFolders])
– [Added in TB 91]
Get the subfolders of the specified folder.
Parameters
[includeSubFolders]
(boolean, optional)
Specifies whether each returned direct child MailFolder should populate its subFolders property and include all its (nested!) subfolders. Defaults to false.
Return type (Promise)
array of MailFolder
Required permissions
getTagFolder(key)
– [Added in TB 127]
Get one of the special unified mailbox tag folders, which are virtual search folders and group messages from all mail accounts based on their tags.
Parameters
key
(string)
The tag key of the requested folder. See messages.tags.list() for the available tags. Throws when specifying an invalid tag key.
Return type (Promise)
Required permissions
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.
Parameters
type
(string)
The requested unified mailbox folder type.
Supported values:
inbox
drafts
sent
trash
templates
archives
junk
[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)
Required permissions
markAsRead(folderId)
– [Added in TB 121]
Marks all messages in a folder as read.
Parameters
Required permissions
move(sourceFolderId, destinationFolderId)
– [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.
Return type (Promise)
Required permissions
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)
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.
Limits the search to the folder with the specified id.
Whether the folder (excluding subfolders) contains messages, or not. Supports to specify a QueryRange (min/max) instead of a simple boolean value (none/some).
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).
Whether the folder has subfolders, or not. Supports to specify a QueryRange (min/max) instead of a simple boolean value (none/some).
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.
[isTag]
(boolean, optional)
Whether the folder is a virtual tag folder, or not. Note: Virtual tag folders are always skipped, unless this property is set to true
[isUnified]
(boolean, optional)
Whether the folder is a unified mailbox folder, or not. Note: Unified mailbox folders are always skipped, unless this property is set to true
[isVirtual]
(boolean, optional)
Whether the 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
Return only folders whose name is matched by the provided string or regular expression.
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.
Match only folders with the specified special use (folders have to match all specified uses).
Return type (Promise)
array of MailFolder
Required permissions
rename(folderId, newName)
Renames a folder.
Return type (Promise)
Required permissions
update(folderId, updateProperties)
– [Added in TB 121]
Updates properties of a folder.
Parameters
updateProperties
(object)
The properties to update.
[isFavorite]
(boolean, optional)
Sets or clears the favorite status.
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
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.
Required permissions
Types
MailFolder
An object describing a folder.
object
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(folderId, [includeSubFolders]) or getSubFolders(folderId, [includeSubFolders]) to obtain hierarchy information.
The id of the account this folder belongs to.
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.
[isTag]
(boolean, optional)
– [Added in TB 121]
Whether this folder is a virtual tag folder.
[isUnified]
(boolean, optional)
Whether this folder is a unified mailbox 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.
The special use of this folder. A folder can have multiple special uses.
Subfolders of this folder. The property may be null, if inclusion of folders had not been requested. The folders will be returned in the same order as used in Thunderbird’s folder pane.
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
Date the folder was last used (precision: seconds).
[newMessageCount]
(integer, optional)
– [Added in TB 121]
Number of new messages in this folder.
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.