compose API
The compose API allows to interact with the message composition window.
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.
accountsRead
See your mail accounts, their identities and their folders.
compose
Read and modify your email messages as you compose and send them.
compose.save
Save composed email messages as drafts or templates.
compose.send
Send composed email messages on your behalf.
Functions
addAttachment(tabId, attachment)
– [Added in TB 78]
Adds an attachment to the message being composed in the specified tab.
Required permissions
beginForward(messageId, [forwardType], [details])
– [Added in TB 67]
Open a new message compose window forwarding a given message.
Note
The compose format can be set by details.isPlainText or by specifying only one of details.body or details.plainTextBody. Otherwise the default compose format of the selected identity is used. If no identity is specified, this function is using the default identity and not the identity of the referenced message.
Parameters
messageId
forwardType
details
beginNew([messageId], [details])
– [Added in TB 67]
Open a new message compose window.
Note
The compose format can be set by details.isPlainText or by specifying only one of details.body or details.plainTextBody. Otherwise the default compose format of the selected identity is used. If no identity is specified, this function is using the default identity and not the identity of the referenced message.
Parameters
messageId
details
beginReply(messageId, [replyType], [details])
– [Added in TB 67]
Open a new message compose window replying to a given message.
Note
The compose format can be set by details.isPlainText or by specifying only one of details.body or details.plainTextBody. Otherwise the default compose format of the selected identity is used. If no identity is specified, this function is using the default identity and not the identity of the referenced message.
Parameters
messageId
replyType
details
getActiveDictionaries(tabId)
– [Added in TB 102]
Returns a ComposeDictionaries object, listing all installed dictionaries, including the information whether they are currently enabled or not.
Required permissions
getAttachmentFile(id)
– [Added in TB 98]
Gets the content of a ComposeAttachment as a File object.
getComposeDetails(tabId)
– [Added in TB 74]
Fetches the current state of a compose window. Currently only a limited amount of information is available, more will be added in later versions.
Required permissions
getComposeState(tabId)
– [Added in TB 90]
Returns information about the current state of the message composer.
listAttachments(tabId)
– [Added in TB 78]
Lists all of the attachments of the message being composed in the specified tab.
Required permissions
removeAttachment(tabId, attachmentId)
– [Added in TB 78]
Removes an attachment from the message being composed in the specified tab.
Required permissions
saveMessage(tabId, [options])
– [Added in TB 102]
Saves the message currently being composed as a draft or as a template. If the save mode is not specified, the message will be saved as a draft. The returned Promise fulfills once the message has been successfully saved.
Parameters
tabId
options
Return type (Promise)
_returns
messages
An array with exactly one element, the saved message.
Note
Starting with Thunderbird version 142, the File Carbon Copy (FCC) configuration is no longer respected during save operations. Regardless of any FCC settings, only one message is saved, and it is stored in the default folder for the given save mode.
mode
Required permissions
sendMessage(tabId, [options])
– [Added in TB 90]
Sends the message currently being composed. If the send mode is not specified or set to default, the message will be send directly if the user is online and placed in the users outbox otherwise. The returned Promise fulfills once the message has been successfully sent or placed in the user’s outbox. Throws when the send process has been aborted by the user, by an onBeforeSend event or if there has been an error while sending the message to the outgoing mail server.
Parameters
tabId
options
Return type (Promise)
_returns
messages
Copies of the sent message. The number of created copies depends on the applied file carbon copy configuration (fcc).
mode
headerMessageId
The header messageId of the outgoing message. Only included for actually sent messages.
Required permissions
setActiveDictionaries(tabId, activeDictionaries)
– [Added in TB 102]
Updates the active dictionaries. Throws if the activeDictionaries array contains unknown or invalid language identifiers.
Required permissions
setComposeDetails(tabId, details)
– [Added in TB 74]
Updates the compose window. The properties of the given ComposeDetails object will be used to overwrite the current values of the specified compose window, so only properties that are to be changed should be included. Modified settings will be treated as user initiated, and turn off further automatic changes on these settings.
Hint
When updating any of the array properties (customHeaders and most address fields), make sure to first get the current values to not accidentally remove all existing entries when setting the new value.
Note
The compose format of an existing compose window cannot be changed.
Required permissions
updateAttachment(tabId, attachmentId, attachment)
– [Added in TB 78]
Updates the name and/or the content of an attachment in the message being composed in the specified tab. If the specified attachment is a cloud file attachment and the associated provider failed to update the attachment, the function will throw an ExtensionError.
Parameters
tabId
attachmentId
attachment
Required permissions
Events
onActiveDictionariesChanged
– [Added in TB 102]
Fired when one or more dictionaries have been activated or deactivated.
Parameters for onActiveDictionariesChanged.addListener(listener)
listener(tab, dictionaries)
A function that will be called when this event occurs.
Parameters passed to the listener function
tab
dictionaries
onAfterSave
– [Added in TB 105]
Fired when saving a message as draft or template succeeded or failed.
Parameters for onAfterSave.addListener(listener)
listener(tab, saveInfo)
A function that will be called when this event occurs.
Parameters passed to the listener function
tab
saveInfo
messages
An array with exactly one element, the saved message.
Note
Starting with Thunderbird version 142, the File Carbon Copy (FCC) configuration is no longer respected during save operations. Regardless of any FCC settings, only one message is saved, and it is stored in the default folder for the given save mode.
mode
error
An error description, if saving the message failed.
Required permissions
onAfterSend
– [Added in TB 105]
Fired when sending a message succeeded or failed.
Parameters for onAfterSend.addListener(listener)
listener(tab, sendInfo)
A function that will be called when this event occurs.
Parameters passed to the listener function
tab
sendInfo
messages
Copies of the sent message. The number of created copies depends on the applied file carbon copy configuration (fcc).
mode
error
An error description, if sending the message failed.
headerMessageId
The header messageId of the outgoing message. Only included for actually sent messages.
Required permissions
onAttachmentAdded
– [Added in TB 78]
Fired when an attachment is added to a message being composed.
Parameters for onAttachmentAdded.addListener(listener)
listener(tab, attachment)
A function that will be called when this event occurs.
Parameters passed to the listener function
tab
attachment
Required permissions
onAttachmentRemoved
– [Added in TB 78]
Fired when an attachment is removed from a message being composed.
Parameters for onAttachmentRemoved.addListener(listener)
listener(tab, attachmentId)
A function that will be called when this event occurs.
Required permissions
onBeforeSend
– [Added in TB 74]
Fired when a message is about to be sent from the compose window. This is a user input event handler. For asynchronous listeners some restrictions apply.
Parameters for onBeforeSend.addListener(listener)
listener(tab, details)
A function that will be called when this event occurs.
Parameters passed to the listener function
tab
details
The current state of the compose window. This is functionally the same as calling the getComposeDetails(tabId) function.
Expected return value of the listener function
compose-on-before-send-returns
cancel
Cancels the send.
details
Updates the compose window. This is functionally the same as calling the setComposeDetails(tabId, details) function.
Required permissions
onComposeStateChanged
– [Added in TB 90]
Fired when the state of the message composer changed.
Parameters for onComposeStateChanged.addListener(listener)
listener(tab, state)
A function that will be called when this event occurs.
onIdentityChanged
– [Added in TB 78]
Fired when the user changes the identity that will be used to send a message being composed.
Parameters for onIdentityChanged.addListener(listener)
listener(tab, identityId)
A function that will be called when this event occurs.
Required permissions
Types
ComposeAttachment
– [Added in TB 78]
Represents an attachment in a message being composed.
ComposeDetails
– [Added in TB 74]
Used by various functions to represent the state of a message being composed. Note that functions using this type may have a partial implementation.
object
additionalFccFolder
An additional fcc folder which can be selected while composing the message, an empty string if not used. The permission is required to use this property.
attachments
Only used in the begin* functions. Attachments to add to the message.
attachPublicPGPKey
Whether the public OpenPGP key of the sending identity should be attached to the message.
attachVCard
Whether or not the vCard of the used identity will be attached to the message during send.
Note
If the value has not been modified, selecting a different identity will load the default value of the new identity.
bcc
body
The HTML content of the message.
cc
customHeaders
Array of custom headers. Headers will be returned in Http-Header-Case (a.k.a. Train-Case). Set an empty array to clear all custom headers.
deliveryFormat
Defines the MIME format of the sent message (ignored on plain text messages). Defaults to auto, which will send html messages as plain text, if they do not include any formatting, and as both otherwise (a multipart/mixed message).
Supported values:
auto
both
html
plaintext
deliveryStatusNotification
Let the sender know when the recipient’s server received the message. Not supported by all servers.
followupTo
from
Caution: Setting a value for from does not change the used identity, it overrides the From header. Many email servers do not accept emails where the From header does not match the sender identity. Must be set to exactly one valid email address.
identityId
The ID of an identity from the accounts API. The settings from the identity will be used in the composed message. If replyTo is also specified, the replyTo property of the identity is overridden. The permission is required to include the identityId.
isModified
Whether the composer is considered modified by the user. A modified composer asks for confirmation, when it is closed.
isPlainText
Whether the message is an HTML message or a plain text message.
newsgroups
A single newsgroup name or an array of newsgroup names.
overrideDefaultFcc
Indicates whether the default fcc setting (defined by the used identity) is being overridden for this message. Setting false will clear the override. Setting true will throw an ExtensionError, if overrideDefaultFccFolder is not set as well. The permission is required to use this property.
overrideDefaultFccFolder
This value overrides the default fcc setting (defined by the used identity) for this message only. Either a MailFolder specifying the folder for the copy of the sent message, or an empty string to not save a copy at all. The permission is required to use this property.
plainTextBody
The plain text content of the message.
priority
relatedMessageId
The id of the original message (in case of draft, template, forward or reply). Read-only. Is undefined in all other cases or if the original message was opened from file.
replyTo
returnReceipt
Add the Disposition-Notification-To header to the message to requests the recipients email client to send a reply once the message has been received. Recipient server may strip the header and the recipient might ignore the request.
selectedEncryptionTechnology
[selectedEncryptionTechnology]
(EncryptionPropertiesSMIME or EncryptionPropertiesOpenPGP, optional)
– [Added in TB 128]
The selected encryption technology (OpenPGP or S/MIME) which is to be used to sign and/or encrypt the message. If the sending identity does not support encryption at all, this will be undefined.
subject
to
type
ComposeDictionaries
– [Added in TB 102]
A dictionary object with entries for all installed dictionaries, having a language identifier as key (for example en-US) and a boolean expression as value, indicating whether that dictionary is enabled for spellchecking or not.
object
ComposeRecipient
– [Added in TB 67]
string
A name and email address in the format Name <email@example.com>, or just an email address.
or
object
ComposeRecipientList
– [Added in TB 74]
or
array of ComposeRecipient
ComposeState
– [Added in TB 90]
Represent the state of the message composer.
CustomHeader
– [Added in TB 100]
A custom header definition.
EncryptionPropertiesOpenPGP
– [Added in TB 128]
object
encryptBody
Whether encryption of the message body using the OpenPGP technology is enabled.
Note
If encryption is enabled, but the preconditions for sending an encrypted message are not met, the message cannot be sent.
encryptSubject
Whether encryption of the message subject using the OpenPGP technology is enabled (only supported if encryption of the body is enabled a well).
name
signMessage
Whether the message will be signed using the OpenPGP technology.
EncryptionPropertiesSMIME
– [Added in TB 128]
object
encryptBody
Whether encryption of the message body using the S/MIME technology is enabled.
Note
If encryption is enabled, but the preconditions for sending an encrypted message are not met, the message cannot be sent.
name
signMessage
Whether the message will be signed using the S/MIME technology
FileAttachment
– [Added in TB 98]
Object used to add, update or rename an attachment in a message being composed.