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
Create, rename, or delete your mail account folders.
accountsRead
See your mail accounts, their identities and their folders.
messagesDelete
Permanently delete your email messages.
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
Required permissions
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
childName
Required permissions
delete(folder)
– [Added in TB 68]
Deletes a folder.
Required permissions
get(folderId, [includeSubFolders])
– [Added in TB 121]
Returns the specified folder.
Parameters
folderId
includeSubFolders
Specifies whether the returned MailFolder should populate its subFolders property and include all its (nested!) subfolders. Defaults to true.
Required permissions
getFolderCapabilities(folder)
– [Added in TB 121]
Get capability information about a folder.
Required permissions
getFolderInfo(folder)
– [Added in TB 91]
Get additional information about a folder.
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
folder
includeSubFolders
Specifies whether each returned parent MailFolder should populate its subFolders property and include all its (nested!) subfolders. Defaults to false.
Required permissions
getSubFolders(folder, [includeSubFolders])
– [Added in TB 91]
Get the subfolders of the specified folder or account.
Parameters
folder
includeSubFolders
Specifies whether each returned direct child MailFolder should populate its subFolders property and include all its (nested!) subfolders. Defaults to true.
Required permissions
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
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. Throws if the requested folder does not exist.
Parameters
type
includeSubFolders
Specifies whether the returned MailFolder should populate its subFolders property and include all its (nested!) subfolders. Defaults to false.
Required permissions
markAsRead(folder)
– [Added in TB 121]
Marks all messages in a folder as read.
Required permissions
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
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
accountId
Limits the search to folders of the account with the specified id.
canAddMessages
Whether the folder supports adding new messages, or not.
canAddSubfolders
Whether the folder supports adding new subfolders, or not.
canBeDeleted
Whether the folder can be deleted, or not.
canBeRenamed
Whether the folder can be renamed, or not.
canDeleteMessages
Whether the folder supports deleting messages, or not.
folderId
Limits the search to the folder with the specified id.
hasMessages
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
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
Whether the folder has subfolders, or not. Supports to specify a QueryRange (min/max) instead of a simple boolean value (none/some).
hasUnreadMessages
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
Whether the folder is a favorite folder, or not.
isRoot
Whether the folder is a root folder, or not.
isTag
Whether the folder is a virtual tag folder, or not. Virtual tag folders are always skipped, unless this property is set to true
isUnified
Whether the folder is a unified mailbox folder, or not. Unified mailbox folders are always skipped, unless this property is set to true
isVirtual
Whether the folder is a virtual search folder, or not.
lastUsed
Date the folder was last used (folder was accessed, user moved or copied messages into the folder or folder received new messages).
lastUsedAsDestination
Date the folder was last used as a destination (user moved or copied messages into the folder).
limit
Limits the number of returned folders. If used together with recent, supports being set to DEFAULT_MOST_RECENT_LIMIT
name
Return only folders whose name is matched by the provided string or regular expression.
path
Return only folders whose path is matched by the provided string or regular expression.
recent
Whether the folder (excluding subfolders) has been used within the last month, or not. The returned folders will be sorted by lastUsed.
sort
specialUse
Match only folders with the specified special use (folders have to match all specified uses).
type
Deprecated. Match only folders with the specified special use.
Required permissions
rename(folder, newName)
– [Added in TB 68]
Renames a folder.
Required permissions
update(folder, updateProperties)
– [Added in TB 121]
Updates properties of a folder.
Parameters
folder
updateProperties
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.
Parameters passed to the listener function
originalFolder
copiedFolder
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.
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.
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.
Parameters passed to the listener function
folder
folderInfo
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.
Parameters passed to the listener function
originalFolder
movedFolder
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.
Parameters passed to the listener function
originalFolder
renamedFolder
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.
Parameters passed to the listener function
originalFolder
updatedFolder
Required permissions
Types
MailFolder
– [Added in TB 68]
An object describing a folder.
object
path
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
The id of the account this folder belongs to.
id
An identifier for the folder.
isFavorite
Whether this folder is a favorite folder.
isRoot
Whether this folder is a root folder.
isTag
Whether this folder is a virtual tag folder.
isUnified
Whether this folder is a unified mailbox folder.
isVirtual
Whether this folder is a virtual search folder.
name
The human-friendly name of this folder.
specialUse
The special use of this folder. A folder can have multiple special uses.
subFolders
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
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
Whether this folder supports adding new messages.
canAddSubfolders
Whether this folder supports adding new subfolders.
canBeDeleted
Whether this folder can be deleted.
canBeRenamed
Whether this folder can be renamed.
canDeleteMessages
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
Deprecated. This information is now available in MailFolder.
lastUsed
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
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
Number of new messages in this folder.
quota
Quota information, if available.
totalMessageCount
Number of messages in this folder.
unreadMessageCount
Number of unread messages in this folder.
MailFolderQuota
– [Added in TB 121]
An object containing quota information.
object
limit
The maximum available quota.
type
unused
The currently unused quota.
used
The currently used quota.
MailFolderSpecialUse
– [Added in TB 121]
Supported values for the special use of a folder.
QueryDateRange
– [Added in TB 137]
An object defining a range for a date value to be used in queries.
object
recent
Whether the date must be considered to be recent by Thunderbird (within the last month) or not, to match the query.
or
QueryRange
– [Added in TB 121]
An object defining a range for an integer value to be used in queries.
RegularExpression
– [Added in TB 121]
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.