compose¶
This message composition window API first appeared in Thunderbird 67 (see bug 1503423).
Permissions¶
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.
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.
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.
Parameters
messageId
(integer)
The message to reply to, as retrieved using other APIs.
[replyType]
(string)
Supported values:
replyToSender
replyToList
replyToAll
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.
Parameters
messageId
(integer)
The message to forward, as retrieved using other APIs.
[forwardType]
(string)
Supported values:
forwardInline
forwardAsAttachment
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)
Required permissions
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.
Required permissions
listAttachments(tabId)¶
– [Added in TB 78]
Lists all of the attachments of the message being composed in the specified tab.
Parameters
tabId
(integer)
addAttachment(tabId, data)¶
– [Added in TB 78]
Adds an attachment to the message being composed in the specified tab.
Parameters
tabId
(integer)
data
(object)
[name]
(string)
The name, as displayed to the user, of this attachment. If not specified, the name of the file object is used.
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)
[name]
(string)
The name, as displayed to the user, of this attachment. If not specified, the name of the file object is used.
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
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.
Updates the compose window. See the setComposeDetails(tabId, details) function for more information.
Required permissions
onAttachmentAdded(tab, attachment)¶
– [Added in TB 78]
Fired when an attachment is added to a message being composed.
onAttachmentRemoved(tab, attachmentId)¶
– [Added in TB 78]
Fired when an attachment is removed from a message being composed.
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.
Required permissions
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 DOMFileobject.
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.
[body]
(string)
[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 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]
[subject]
(string)
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]
string
A name and email address in the format “Name <email@example.com>”, or just an email address.
OR
array of ComposeRecipient