compose

This message composition window API first appeared in Thunderbird 67 (see bug 1503423).

Permissions

compose
Read and modify your email messages as you compose and send them

Functions

beginNew([messageId], [details])

Open a new message compose window. If the provided ComposeDetails object does not provide body, plainTextBody or isPlainText, the default compose format of the used/default identity is used. The accounts API can be used to get the used/default identity and its default compose format.

Parameters
[messageId]
(integer)
– [Added in TB 84, backported to TB 78.7.0]
If specified, the message or template to edit as a new message.
[details]
(ComposeDetails)
Return type (Promise)
Tab
– [Added in TB 77]

beginReply(messageId, [replyType], [details])

Open a new message compose window replying to a given message. If the provided ComposeDetails object does not provide body, plainTextBody or isPlainText, the default compose format of the used/default identity is used. The accounts API can be used to get the used/default identity and its default compose format.

Parameters
messageId
(integer)
The message to reply to, as retrieved using other APIs.
[replyType]
(string)

Supported values:

replyToSender
replyToList
replyToAll
[details]
(ComposeDetails)
– [Added in TB 76]
Return type (Promise)
Tab
– [Added in TB 77]

beginForward(messageId, [forwardType], [details])

Open a new message compose window forwarding a given message. If the provided ComposeDetails object does not provide body, plainTextBody or isPlainText, the default compose format of the used/default identity is used. The accounts API can be used to get the used/default identity and its default compose format.

Parameters
messageId
(integer)
The message to forward, as retrieved using other APIs.
[forwardType]
(string)

Supported values:

forwardInline
forwardAsAttachment
[details]
(ComposeDetails)
Return type (Promise)
Tab
– [Added in TB 77]

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.

Parameters
tabId
(integer)
Return type (Promise)
ComposeDetails
Required permissions
  • compose

setComposeDetails(tabId, details)

– [Added in TB 74]

Updates the compose window. Specify only fields that you want to change. Currently only the to/cc/bcc/replyTo/followupTo/newsgroups fields and the subject are implemented. It is not possible to change the compose format.

Parameters
tabId
(integer)
details
(ComposeDetails)
The compose format of an already opened compose window cannot be changed. Setting details.body, details.plainTextBody or details.isPlaintext will fail if the compose format of the compose window does not match. Use getComposeDetails(tabId) to get the current compose format.
Required permissions
  • compose

listAttachments(tabId)

– [Added in TB 78]

Lists all of the attachments of the message being composed in the specified tab.

Parameters
tabId
(integer)
Return type (Promise)
array of ComposeAttachment

addAttachment(tabId, data)

– [Added in TB 78]

Adds an attachment to the message being composed in the specified tab.

Parameters
tabId
(integer)
data
(object)
file
(File)
[name]
(string)
The name, as displayed to the user, of this attachment. If not specified, the name of the file object is used.
Return type (Promise)
ComposeAttachment

updateAttachment(tabId, attachmentId, data)

– [Added in TB 78]

Renames and/or replaces the contents of an attachment to the message being composed in the specified tab.

Parameters
tabId
(integer)
attachmentId
(integer)
data
(object)
[file]
(File)
[name]
(string)
The name, as displayed to the user, of this attachment. If not specified, the name of the file object is used.
Return type (Promise)
ComposeAttachment

removeAttachment(tabId, attachmentId)

– [Added in TB 78]

Removes an attachment from the message being composed in the specified tab.

Parameters
tabId
(integer)
attachmentId
(integer)

Events

onBeforeSend(tab, details)

– [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 event listeners
tab
(Tab)
– [Added in TB 74.0b2]
details
(ComposeDetails)
The current state of the compose window. This is functionally the same as the getComposeDetails(tabId) function.
Expected return value of event listeners
object
[cancel]
(boolean)
Cancels the send.
[details]
(ComposeDetails)
Updates the compose window. See the setComposeDetails(tabId, details) function for more information.
Required permissions
  • compose

onAttachmentAdded(tab, attachment)

– [Added in TB 78]

Fired when an attachment is added to a message being composed.

Parameters for event listeners
tab
(Tab)
attachment
(ComposeAttachment)

onAttachmentRemoved(tab, attachmentId)

– [Added in TB 78]

Fired when an attachment is removed from a message being composed.

Parameters for event listeners
tab
(Tab)
attachmentId
(integer)

onIdentityChanged(tab, identityId)

– [Added in TB 78.0b2]

Fired when the user changes the identity that will be used to send a message being composed.

Parameters for event listeners
tab
(Tab)
identityId
(string)
Required permissions
  • accountsRead

Types

ComposeAttachment

– [Added in TB 78]

Represents an attachment in a message being composed.

object
id
(integer)
A unique identifier for this attachment.
name
(string)
The name, as displayed to the user, of this attachment. This is usually but not always the filename of the attached file.
size
(integer)
– [Added in TB 83, backported to TB 78.5.0]
The size in bytes of this attachment.
  • getFile() Retrieves the contents of the attachment as a DOM File object.

ComposeDetails

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
[attachments]
(array of object)
– [Added in TB 82, backported to TB 78.4.0]
Attachments to add to the message. Only used in the begin* functions.
[bcc]
(ComposeRecipientList)
[body]
(string)
[cc]
(ComposeRecipientList)
[followupTo]
(ComposeRecipientList)
– [Added in TB 74]
[from]
(ComposeRecipient)
– [Added in TB 88]
Caution: Setting a value for from does not change the used identity, it overrides the FROM header. Many e-mail servers do not accept emails where the FROM header does not match the sender identity. Must be set to exactly one valid e-mail address.
[identityId]
(string)
– [Added in TB 76]
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 accountsRead is required to include the identityId.
[isPlainText]
(boolean)
– [Added in TB 75]
[newsgroups]
(string or array of string)
– [Added in TB 74]
[plainTextBody]
(string)
– [Added in TB 75]
[replyTo]
(ComposeRecipientList)
[subject]
(string)
[to]
(ComposeRecipientList)
[type]
(string)
– [Added in TB 88]

Read-only. The type of the message being composed, depending on how the compose window was opened by the user.

Supported values:

draft
new
reply
forward

ComposeRecipient

string
A name and email address in the format “Name <email@example.com>”, or just an email address.

OR

object
id
(string)
The ID of a contact or mailing list from the contacts and mailingLists APIs.
type
(string)

Which sort of object this ID is for.

Supported values:

contact
mailingList

ComposeRecipientList

– [Added in TB 74]
ComposeRecipient

OR

array of ComposeRecipient