compose API
The compose API first appeared in Thunderbird 67. It allows to interact with the message composition window.
Permissions
Read and modify your email messages as you compose and send them
Send composed email messages on your behalf
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, optional)
– [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. 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, optional)
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. 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, optional)
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.
Parameters
tabId
(integer)
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
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
Required permissions
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, optional)
The name, as displayed to the user, of this attachment. If not specified, the name of the file object is used.
Return type (Promise)
Required permissions
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, optional)
The name, as displayed to the user, of this attachment. If not specified, the name of the file object is used.
Return type (Promise)
Required permissions
removeAttachment(tabId, attachmentId)
– [Added in TB 78]
Removes an attachment from the message being composed in the specified tab.
Parameters
tabId
(integer)
attachmentId
(integer)
Required permissions
sendMessage(tabId, [options])
– [Added in TB 90]
Sends the message currently being composed.
Parameters
tabId
(integer)
[options]
(object, optional)
mode
(string)
Supported values:
default
sendNow
sendLater
Return type (Promise)
boolean
Required permissions
getComposeState(tabId)
– [Added in TB 90]
Returns information about the current state of the message composer.
Parameters
tabId
(integer)
Return type (Promise)
Events
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
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
object
[cancel]
(boolean, optional)
Cancels the send.
Updates the compose window. This is functionally the same as calling the setComposeDetails(tabId, details) function.
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.
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
onIdentityChanged
– [Added in TB 78.0b2]
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
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.
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, optional)
The name of this attachment, as displayed to the user.
[size]
(integer, optional)
– [Added in TB 83, backported to TB 78.5.0]
The size in bytes of this attachment. Read-only.
getFile()Retrieves the contents of the attachment as a 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, optional)
– [Added in TB 82, backported to TB 78.4.0]
Attachments to add to the message. Only used in the begin* functions.
[body]
(string, optional)
The HTML content of the message.
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]
(string, optional)
– [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, optional)
– [Added in TB 75]
Whether the message is an HTML message or a plain text message.
[newsgroups]
(string or array of string, optional)
– [Added in TB 74]
[plainTextBody]
(string, optional)
– [Added in TB 75]
The plain text content of the message.
[relatedMessageId]
(integer, optional)
– [Added in TB 95, backported to TB 91.3.1]
The id of the original message (in case of draft, template, forward or reply). Read-only. Is null in all other cases or if the original message was opened from file.
[subject]
(string, optional)
[type]
(string, optional)
– [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
redirect
– [Added in TB 90]
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 API and mailingLists API.
type
(string)
Which sort of object this ID is for.
Supported values:
contact
mailingList
ComposeRecipientList
– [Added in TB 74]
OR
array of ComposeRecipient
ComposeState
– [Added in TB 90]
Represent the state of the message composer.
object
canSendLater
(boolean)
The message can be send later.
canSendNow
(boolean)
The message can be send now.