compose API

Permissions

The following permissions influence the behavior of the API. Depending on which permissions are requested, additional methods might be available, or certain data may be included in responses.

Hint

Request permissions only when needed. Unnecessary requests may result in rejection during ATN review.

accountsRead

accountsRead

See your mail accounts, their identities and their folders.

compose

compose

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

compose.save

compose.save

Save composed email messages as drafts or templates.

compose.send

compose.send

Send composed email messages on your behalf.

Functions

addAttachment(tabId, attachment)

– [Added in TB 78]

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

Parameters

tabId

tabId

(integer)

attachment

Return type (Promise)

_returns

– [Added in TB 96]

Required permissions

  • compose

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

– [Added in TB 67]

Open a new message compose window forwarding a given message.

Note

The compose format can be set by details.isPlainText or by specifying only one of details.body or details.plainTextBody. Otherwise the default compose format of the selected identity is used. If no identity is specified, this function is using the default identity and not the identity of the referenced message.

Parameters

messageId

messageId

The message to forward, as retrieved using other APIs.

forwardType

[forwardType]

(string, optional)

Supported values:

forwardAsAttachment

forwardAsAttachment

forwardInline

forwardInline

details

[details]

(ComposeDetails, optional)

Return type (Promise)

_returns

Tab

– [Added in TB 89]

beginNew([messageId], [details])

– [Added in TB 67]

Open a new message compose window.

Note

The compose format can be set by details.isPlainText or by specifying only one of details.body or details.plainTextBody. Otherwise the default compose format of the selected identity is used. If no identity is specified, this function is using the default identity and not the identity of the referenced message.

Parameters

messageId

[messageId]

(MessageId, optional)

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

details

[details]

(ComposeDetails, optional)

– [Added in TB 84]

Return type (Promise)

_returns

Tab

– [Added in TB 89]

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

– [Added in TB 67]

Open a new message compose window replying to a given message.

Note

The compose format can be set by details.isPlainText or by specifying only one of details.body or details.plainTextBody. Otherwise the default compose format of the selected identity is used. If no identity is specified, this function is using the default identity and not the identity of the referenced message.

Parameters

messageId

messageId

The message to reply to, as retrieved using other APIs.

replyType

[replyType]

(string, optional)

Supported values:

replyToAll

replyToAll

replyToList

replyToList

replyToSender

replyToSender

details

[details]

(ComposeDetails, optional)

– [Added in TB 76]

Return type (Promise)

_returns

Tab

– [Added in TB 89]

getActiveDictionaries(tabId)

– [Added in TB 102]

Returns a ComposeDictionaries object, listing all installed dictionaries, including the information whether they are currently enabled or not.

Parameters

tabId

tabId

(integer)

Return type (Promise)

_returns

Required permissions

  • compose

getAttachmentFile(id)

– [Added in TB 98]

Gets the content of a ComposeAttachment as a File object.

Parameters

id

id

(integer)

The unique identifier for the attachment.

Return type (Promise)

_returns

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

tabId

(integer)

Return type (Promise)

_returns

– [Added in TB 89]

Required permissions

  • compose

getComposeState(tabId)

– [Added in TB 90]

Returns information about the current state of the message composer.

Parameters

tabId

tabId

(integer)

Return type (Promise)

_returns

listAttachments(tabId)

– [Added in TB 78]

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

Parameters

tabId

tabId

(integer)

Return type (Promise)

_returns

– [Added in TB 96]

Required permissions

  • compose

removeAttachment(tabId, attachmentId)

– [Added in TB 78]

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

Parameters

tabId

tabId

(integer)

attachmentId

attachmentId

(integer)

Required permissions

  • compose

saveMessage(tabId, [options])

– [Added in TB 102]

Saves the message currently being composed as a draft or as a template. If the save mode is not specified, the message will be saved as a draft. The returned Promise fulfills once the message has been successfully saved.

Parameters

tabId

tabId

(integer)

options

[options]

(object, optional)

mode

mode

(string)

Supported values:

draft

draft

template

template

Return type (Promise)

_returns

object

messages

messages

(array of MessageHeader)

An array with exactly one element, the saved message.

Note

Starting with Thunderbird version 142, the File Carbon Copy (FCC) configuration is no longer respected during save operations. Regardless of any FCC settings, only one message is saved, and it is stored in the default folder for the given save mode.

mode

mode

(string)

The used save mode.

Supported values:

draft

draft

template

template

Required permissions

  • compose.save

sendMessage(tabId, [options])

– [Added in TB 90]

Sends the message currently being composed. If the send mode is not specified or set to default, the message will be send directly if the user is online and placed in the users outbox otherwise. The returned Promise fulfills once the message has been successfully sent or placed in the user’s outbox. Throws when the send process has been aborted by the user, by an onBeforeSend event or if there has been an error while sending the message to the outgoing mail server.

Parameters

tabId

tabId

(integer)

options

[options]

(object, optional)

mode

mode

(string)

Supported values:

default

default

sendLater

sendLater

sendNow

sendNow

Return type (Promise)

_returns

object

messages

messages

(array of MessageHeader)

– [Added in TB 102]

Copies of the sent message. The number of created copies depends on the applied file carbon copy configuration (fcc).

mode

mode

(string)

– [Added in TB 102]

The used send mode.

Supported values:

sendLater

sendLater

sendNow

sendNow

headerMessageId

[headerMessageId]

(string, optional)

– [Added in TB 102]

The header messageId of the outgoing message. Only included for actually sent messages.

Required permissions

  • compose.send

setActiveDictionaries(tabId, activeDictionaries)

– [Added in TB 102]

Updates the active dictionaries. Throws if the activeDictionaries array contains unknown or invalid language identifiers.

Parameters

tabId

tabId

(integer)

activeDictionaries

activeDictionaries

(array of string)

Required permissions

  • compose

setComposeDetails(tabId, details)

– [Added in TB 74]

Updates the compose window. The properties of the given ComposeDetails object will be used to overwrite the current values of the specified compose window, so only properties that are to be changed should be included. Modified settings will be treated as user initiated, and turn off further automatic changes on these settings.

Hint

When updating any of the array properties (customHeaders and most address fields), make sure to first get the current values to not accidentally remove all existing entries when setting the new value.

Note

The compose format of an existing compose window cannot be changed.

Parameters

tabId

tabId

(integer)

details

details

Required permissions

  • compose

updateAttachment(tabId, attachmentId, attachment)

– [Added in TB 78]

Updates the name and/or the content of an attachment in the message being composed in the specified tab. If the specified attachment is a cloud file attachment and the associated provider failed to update the attachment, the function will throw an ExtensionError.

Parameters

tabId

tabId

(integer)

attachmentId

attachmentId

(integer)

attachment

attachment

Return type (Promise)

_returns

– [Added in TB 96]

Required permissions

  • compose

Events

onActiveDictionariesChanged

– [Added in TB 102]

Fired when one or more dictionaries have been activated or deactivated.

Parameters for onActiveDictionariesChanged.addListener(listener)

listener(tab, dictionaries)

listener(tab, dictionaries)

A function that will be called when this event occurs.

Parameters passed to the listener function

tab

tab

(Tab)

dictionaries

dictionaries

onAfterSave

– [Added in TB 105]

Fired when saving a message as draft or template succeeded or failed.

Parameters for onAfterSave.addListener(listener)

listener(tab, saveInfo)

listener(tab, saveInfo)

A function that will be called when this event occurs.

Parameters passed to the listener function

tab

tab

(Tab)

saveInfo

saveInfo

(object)

messages

messages

(array of MessageHeader)

An array with exactly one element, the saved message.

Note

Starting with Thunderbird version 142, the File Carbon Copy (FCC) configuration is no longer respected during save operations. Regardless of any FCC settings, only one message is saved, and it is stored in the default folder for the given save mode.

mode

mode

(string)

The used save mode.

Supported values:

autoSave

autoSave

– [Added in TB 125]

draft

draft

template

template

error

[error]

(string, optional)

An error description, if saving the message failed.

Required permissions

  • compose

onAfterSend

– [Added in TB 105]

Fired when sending a message succeeded or failed.

Parameters for onAfterSend.addListener(listener)

listener(tab, sendInfo)

listener(tab, sendInfo)

A function that will be called when this event occurs.

Parameters passed to the listener function

tab

tab

(Tab)

sendInfo

sendInfo

(object)

messages

messages

(array of MessageHeader)

Copies of the sent message. The number of created copies depends on the applied file carbon copy configuration (fcc).

mode

mode

(string)

The used send mode.

Supported values:

sendLater

sendLater

sendNow

sendNow

error

[error]

(string, optional)

An error description, if sending the message failed.

headerMessageId

[headerMessageId]

(string, optional)

The header messageId of the outgoing message. Only included for actually sent messages.

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)

listener(tab, attachment)

A function that will be called when this event occurs.

Parameters passed to the listener function

tab

tab

(Tab)

attachment

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)

listener(tab, attachmentId)

A function that will be called when this event occurs.

Parameters passed to the listener function

tab

tab

(Tab)

attachmentId

attachmentId

(integer)

Required permissions

  • compose

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)

listener(tab, details)

A function that will be called when this event occurs.

Parameters passed to the listener function

tab

tab

(Tab)

details

details

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

compose-on-before-send-returns

object

cancel

[cancel]

(boolean, optional)

Cancels the send.

details

[details]

(ComposeDetails, optional)

Updates the compose window. This is functionally the same as calling the setComposeDetails(tabId, details) function.

Required permissions

  • compose

onComposeStateChanged

– [Added in TB 90]

Fired when the state of the message composer changed.

Parameters for onComposeStateChanged.addListener(listener)

listener(tab, state)

listener(tab, state)

A function that will be called when this event occurs.

Parameters passed to the listener function

tab

tab

(Tab)

state

state

onIdentityChanged

– [Added in TB 78]

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)

listener(tab, identityId)

A function that will be called when this event occurs.

Parameters passed to the listener function

tab

tab

(Tab)

identityId

identityId

(string)

Required permissions

  • accountsRead

Types

ComposeAttachment

– [Added in TB 78]

Represents an attachment in a message being composed.

object

id

id

(integer)

A unique identifier for this attachment.

name

[name]

(string, optional)

The name of this attachment, as displayed to the user.

size

[size]

(integer, optional)

– [Added in TB 83]

The size in bytes of this attachment. Read-only.

ComposeDetails

– [Added in TB 74]

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

additionalFccFolder

[additionalFccFolder]

(MailFolder or string or MailFolderId, optional)

– [Added in TB 102]

An additional fcc folder which can be selected while composing the message, an empty string if not used. The permission accountsRead is required to use this property.

attachments

[attachments]

(array of FileAttachment or ComposeAttachment, optional)

– [Added in TB 82]

Only used in the begin* functions. Attachments to add to the message.

attachPublicPGPKey

[attachPublicPGPKey]

(boolean, optional)

– [Added in TB 128]

Whether the public OpenPGP key of the sending identity should be attached to the message.

attachVCard

[attachVCard]

(boolean, optional)

– [Added in TB 102]

Whether or not the vCard of the used identity will be attached to the message during send.

Note

If the value has not been modified, selecting a different identity will load the default value of the new identity.

bcc

[bcc]

(ComposeRecipientList, optional)

body

[body]

(string, optional)

The HTML content of the message.

cc

[cc]

(ComposeRecipientList, optional)

customHeaders

[customHeaders]

(array of CustomHeader, optional)

– [Added in TB 100]

Array of custom headers. Headers will be returned in Http-Header-Case (a.k.a. Train-Case). Set an empty array to clear all custom headers.

deliveryFormat

[deliveryFormat]

(string, optional)

– [Added in TB 102]

Defines the MIME format of the sent message (ignored on plain text messages). Defaults to auto, which will send html messages as plain text, if they do not include any formatting, and as both otherwise (a multipart/mixed message).

Supported values:

auto

auto

both

both

html

html

plaintext

plaintext

deliveryStatusNotification

[deliveryStatusNotification]

(boolean, optional)

– [Added in TB 102]

Let the sender know when the recipient’s server received the message. Not supported by all servers.

followupTo

[followupTo]

(ComposeRecipientList, optional)

from

[from]

(ComposeRecipient, optional)

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

[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 accountsRead is required to include the identityId.

isModified

[isModified]

(boolean, optional)

– [Added in TB 125]

Whether the composer is considered modified by the user. A modified composer asks for confirmation, when it is closed.

isPlainText

[isPlainText]

(boolean, optional)

– [Added in TB 75]

Whether the message is an HTML message or a plain text message.

newsgroups

[newsgroups]

(string or array of string, optional)

A single newsgroup name or an array of newsgroup names.

overrideDefaultFcc

[overrideDefaultFcc]

(boolean, optional)

– [Added in TB 102]

Indicates whether the default fcc setting (defined by the used identity) is being overridden for this message. Setting false will clear the override. Setting true will throw an ExtensionError, if overrideDefaultFccFolder is not set as well. The permission accountsRead is required to use this property.

overrideDefaultFccFolder

[overrideDefaultFccFolder]

(MailFolder or string or MailFolderId, optional)

– [Added in TB 102]

This value overrides the default fcc setting (defined by the used identity) for this message only. Either a MailFolder specifying the folder for the copy of the sent message, or an empty string to not save a copy at all. The permission accountsRead is required to use this property.

plainTextBody

[plainTextBody]

(string, optional)

– [Added in TB 75]

The plain text content of the message.

priority

[priority]

(string, optional)

– [Added in TB 102]

The priority of the message.

Supported values:

high

high

highest

highest

low

low

lowest

lowest

normal

normal

relatedMessageId

[relatedMessageId]

(MessageId, optional)

– [Added in TB 95]

The id of the original message (in case of draft, template, forward or reply). Read-only. Is undefined in all other cases or if the original message was opened from file.

replyTo

[replyTo]

(ComposeRecipientList, optional)

returnReceipt

[returnReceipt]

(boolean, optional)

– [Added in TB 102]

Add the Disposition-Notification-To header to the message to requests the recipients email client to send a reply once the message has been received. Recipient server may strip the header and the recipient might ignore the request.

selectedEncryptionTechnology

[selectedEncryptionTechnology]

– [Added in TB 128]

The selected encryption technology (OpenPGP or S/MIME) which is to be used to sign and/or encrypt the message. If the sending identity does not support encryption at all, this will be undefined.

subject

[subject]

(string, optional)

to

[to]

(ComposeRecipientList, optional)

type

[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

draft

forward

forward

new

new

redirect

redirect

– [Added in TB 90]

reply

reply

ComposeDictionaries

– [Added in TB 102]

A dictionary object with entries for all installed dictionaries, having a language identifier as key (for example en-US) and a boolean expression as value, indicating whether that dictionary is enabled for spellchecking or not.

object

ComposeRecipient

– [Added in TB 67]

string

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

or

object

id

id

(string)

The ID of a contact or mailing list from the contacts API or mailingLists API.

type

type

(string)

Which sort of object this ID is for.

Supported values:

contact

contact

mailingList

mailingList

ComposeRecipientList

– [Added in TB 74]

or

array of ComposeRecipient

ComposeState

– [Added in TB 90]

Represent the state of the message composer.

object

canSendLater

canSendLater

(boolean)

The message can be send later.

canSendNow

canSendNow

(boolean)

The message can be send now.

CustomHeader

– [Added in TB 100]

A custom header definition.

object

name

name

(string)

Name of a custom header, must be prefixed by X- (but not by X-Mozilla-) or be one of the explicitly allowed headers (MSIP_Labels)

value

value

(string)

EncryptionPropertiesOpenPGP

– [Added in TB 128]

object

encryptBody

encryptBody

(boolean)

Whether encryption of the message body using the OpenPGP technology is enabled.

Note

If encryption is enabled, but the preconditions for sending an encrypted message are not met, the message cannot be sent.

encryptSubject

encryptSubject

(boolean)

Whether encryption of the message subject using the OpenPGP technology is enabled (only supported if encryption of the body is enabled a well).

name

name

(string)

signMessage

signMessage

(boolean)

Whether the message will be signed using the OpenPGP technology.

EncryptionPropertiesSMIME

– [Added in TB 128]

object

encryptBody

encryptBody

(boolean)

Whether encryption of the message body using the S/MIME technology is enabled.

Note

If encryption is enabled, but the preconditions for sending an encrypted message are not met, the message cannot be sent.

name

name

(string)

signMessage

signMessage

(boolean)

Whether the message will be signed using the S/MIME technology

FileAttachment

– [Added in TB 98]

Object used to add, update or rename an attachment in a message being composed.

object

file

[file]

(File, optional)

The new content for the attachment.

name

[name]

(string, optional)

The new name for the attachment, as displayed to the user. If not specified, the name of the provided file object is used.