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([details])

Open a compose window for a new message.

Parameters
[details]
Return type (Promise)
– [Added in TB 77]

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

Open a compose window and load a given message in reply mode.

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

Supported values:

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

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

Open a compose window and load a given message in forward mode.

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

Supported values:

forwardInline
forwardAsAttachment
[details]
Return type (Promise)
– [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)
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.

Parameters
tabId
(integer)
details
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)

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.

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.

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.

Parameters for event listeners
tab
(Tab)
– [Added in TB 74.0b2]
details
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]
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

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]
Attachments to add to the message. Only used in the begin* functions.
[body]
(string)
[followupTo]
– [Added in TB 74]
[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]
[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