accounts API

The accounts API first appeared in Thunderbird 66.

Permissions

accountsRead

See your mail accounts, their identities and their folders

Note

The permission accountsRead is required to use messenger.accounts.*.

Functions

get(accountId, [includeFolders])

Returns details of the requested account, or null if it doesn’t exist.

Parameters

accountId

(string)

[includeFolders]

(boolean, optional)

– [Added in TB 91]

Specifies whether the returned MailAccount object should included the account’s folders. Defaults to true.

Return type (Promise)

Required permissions

  • accountsRead

getDefault([includeFolders])

– [Added in TB 85, backported to TB 78.7.0]

Returns the default account, or null if it is not defined.

Parameters

[includeFolders]

(boolean, optional)

– [Added in TB 91]

Specifies whether the returned MailAccount object should included the account’s folders. Defaults to true.

Return type (Promise)

Required permissions

  • accountsRead

getDefaultIdentity(accountId)

– [Added in TB 85, backported to TB 78.7.0]

Returns the default identity for an account, or null if it is not defined.

Parameters

accountId

(string)

Return type (Promise)

Required permissions

  • accountsRead

list([includeFolders])

Returns all mail accounts. They will be returned in the same order as used in Thunderbird’s folder pane.

Parameters

[includeFolders]

(boolean, optional)

– [Added in TB 91]

Specifies whether the returned MailAccount objects should included their account’s folders. Defaults to true.

Return type (Promise)

array of MailAccount

Required permissions

  • accountsRead

setDefaultIdentity(accountId, identityId)

– [Added in TB 76]

Sets the default identity for an account.

Parameters

accountId

(string)

identityId

(string)

Required permissions

  • accountsRead

Events

onCreated

– [Added in TB 98]

Fired when a new account has been created.

Parameters for onCreated.addListener(listener)

listener(id, account)

A function that will be called when this event occurs.

Parameters passed to the listener function

id

(string)

account

Required permissions

  • accountsRead

onDeleted

– [Added in TB 98]

Fired when an account has been removed.

Parameters for onDeleted.addListener(listener)

listener(id)

A function that will be called when this event occurs.

Parameters passed to the listener function

id

(string)

Required permissions

  • accountsRead

onUpdated

– [Added in TB 98]

Fired when a property of an account has been modified. Folders and identities of accounts are not monitored by this event, use the dedicated folder and identity events instead. A changed defaultIdentity is reported only after a different identity has been assigned as default identity, but not after a property of the default identity has been changed.

Parameters for onUpdated.addListener(listener)

listener(id, changedValues)

A function that will be called when this event occurs.

Parameters passed to the listener function

id

(string)

changedValues

(object)

defaultIdentity

The default identity of this account.

name

(string)

The human-friendly name of this account.

Required permissions

  • accountsRead

Types

MailAccount

An object describing a mail account, as returned for example by the list([includeFolders]) and get(accountId, [includeFolders]) methods. The folders property is only included if requested.

object

id

(string)

A unique identifier for this account.

identities

(array of MailIdentity)

– [Added in TB 76]

The identities associated with this account. The default identity is listed first, others in no particular order.

name

(string)

The human-friendly name of this account.

type

(string)

What sort of account this is, e.g. imap, nntp, or pop3.

[folders]

(array of MailFolder, optional)

The folders for this account are only included if requested.

Examples

Extracting IMAP accounts

The following code can be used to find all IMAP accounts

// Get all accounts.
let accounts = await messenger.accounts.list();

// Filter on accounts with type "imap".
let imapAccounts = accounts.filter(account => account.type == "imap")