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

compose.send

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)

– [Added in TB 84, backported to TB 78.7.0]

If specified, the message or template to edit as a new message.

[details]

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]

– [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]

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)

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

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)

Required permissions

  • compose

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)

Required permissions

  • compose

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)

Required permissions

  • compose

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

  • compose

sendMessage(tabId, [options])

– [Added in TB 90]

Sends the message currently being composed.

Parameters

tabId

(integer)

[options]

(object)

mode

(string)

Supported values:

default

sendNow

sendLater

Return type (Promise)

boolean

Required permissions

  • compose.send

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

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 the listener function

object

[cancel]

(boolean)

Cancels the send.

[details]

Updates the compose window. See the setComposeDetails(tabId, details) function for more information.

Required permissions

  • compose

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

(Tab)

attachment

Required permissions

  • compose

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.

Parameters passed to the listener function

tab

(Tab)

attachmentId

(integer)

Required permissions

  • compose

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.

Parameters passed to the listener function

tab

(Tab)

identityId

(string)

Required permissions

  • accountsRead

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.

Parameters passed to the listener function

tab

(Tab)

state

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.

[body]

(string)

[followupTo]

– [Added in TB 74]

[from]

– [Added in TB 88]

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)

– [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)

[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

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 and mailingLists APIs.

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.