This message composition window API first appeared in Thunderbird 67 (see bug 1503423).
.. rst-class:: api-main-section
.. api-member:: :name: :permission:`compose` Read and modify your email messages as you compose and send them
.. rst-class:: api-main-section
.. api-section-annotation-hack::
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.
.. api-header::
:label: Parameters
.. api-member::
:name: [``messageId``]
:type: (integer)
:annotation: -- [Added in TB 84, backported to TB 78.7.0]
If specified, the message or template to edit as a new message.
.. api-member::
:name: [``details``]
:type: (:ref:`compose.ComposeDetails`)
.. api-header::
:label: Return type (`Promise`_)
.. api-member::
:type: :ref:`tabs.Tab`
:annotation: -- [Added in TB 77]
.. _Promise: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
.. api-section-annotation-hack::
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.
.. api-header::
:label: Parameters
.. api-member::
:name: ``messageId``
:type: (integer)
The message to reply to, as retrieved using other APIs.
.. api-member::
:name: [``replyType``]
:type: (`string`)
Supported values:
.. api-member::
:name: ``replyToSender``
.. api-member::
:name: ``replyToList``
.. api-member::
:name: ``replyToAll``
.. api-member::
:name: [``details``]
:type: (:ref:`compose.ComposeDetails`)
:annotation: -- [Added in TB 76]
.. api-header::
:label: Return type (`Promise`_)
.. api-member::
:type: :ref:`tabs.Tab`
:annotation: -- [Added in TB 77]
.. _Promise: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
.. api-section-annotation-hack::
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.
.. api-header::
:label: Parameters
.. api-member::
:name: ``messageId``
:type: (integer)
The message to forward, as retrieved using other APIs.
.. api-member::
:name: [``forwardType``]
:type: (`string`)
Supported values:
.. api-member::
:name: ``forwardInline``
.. api-member::
:name: ``forwardAsAttachment``
.. api-member::
:name: [``details``]
:type: (:ref:`compose.ComposeDetails`)
.. api-header::
:label: Return type (`Promise`_)
.. api-member::
:type: :ref:`tabs.Tab`
:annotation: -- [Added in TB 77]
.. _Promise: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
.. api-section-annotation-hack:: -- [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.
.. api-header::
:label: Parameters
.. api-member::
:name: ``tabId``
:type: (integer)
.. api-header::
:label: Return type (`Promise`_)
.. api-member::
:type: :ref:`compose.ComposeDetails`
.. _Promise: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
.. api-header:: :label: Required permissions - :permission:`compose`
.. api-section-annotation-hack:: -- [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.
.. api-header::
:label: Parameters
.. api-member::
:name: ``tabId``
:type: (integer)
.. api-member::
:name: ``details``
:type: (:ref:`compose.ComposeDetails`)
.. api-header:: :label: Required permissions - :permission:`compose`
.. api-section-annotation-hack:: -- [Added in TB 78]
Lists all of the attachments of the message being composed in the specified tab.
.. api-header::
:label: Parameters
.. api-member::
:name: ``tabId``
:type: (integer)
.. api-section-annotation-hack:: -- [Added in TB 78]
Adds an attachment to the message being composed in the specified tab.
.. api-header::
:label: Parameters
.. api-member::
:name: ``tabId``
:type: (integer)
.. api-member::
:name: ``data``
:type: (object)
.. api-member::
:name: ``file``
:type: (`File <https://developer.mozilla.org/en-US/docs/Web/API/File>`_)
.. api-member::
:name: [``name``]
:type: (string)
The name, as displayed to the user, of this attachment. If not specified, the name of the ``file`` object is used.
.. api-section-annotation-hack:: -- [Added in TB 78]
Renames and/or replaces the contents of an attachment to the message being composed in the specified tab.
.. api-header::
:label: Parameters
.. api-member::
:name: ``tabId``
:type: (integer)
.. api-member::
:name: ``attachmentId``
:type: (integer)
.. api-member::
:name: ``data``
:type: (object)
.. api-member::
:name: [``file``]
:type: (`File <https://developer.mozilla.org/en-US/docs/Web/API/File>`_)
.. api-member::
:name: [``name``]
:type: (string)
The name, as displayed to the user, of this attachment. If not specified, the name of the ``file`` object is used.
.. api-section-annotation-hack:: -- [Added in TB 78]
Removes an attachment from the message being composed in the specified tab.
.. api-header::
:label: Parameters
.. api-member::
:name: ``tabId``
:type: (integer)
.. api-member::
:name: ``attachmentId``
:type: (integer)
.. rst-class:: api-main-section
.. api-section-annotation-hack:: -- [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.
.. api-header::
:label: Parameters for event listeners
.. api-member::
:name: ``tab``
:type: (:ref:`tabs.Tab`)
:annotation: -- [Added in TB 74.0b2]
.. api-member::
:name: ``details``
:type: (:ref:`compose.ComposeDetails`)
The current state of the compose window. This is functionally the same as the :ref:`compose.getComposeDetails` function.
.. api-header::
:label: Expected return value of event listeners
.. api-member::
:type: object
.. api-member::
:name: [``cancel``]
:type: (boolean)
Cancels the send.
.. api-member::
:name: [``details``]
:type: (:ref:`compose.ComposeDetails`)
Updates the compose window. See the :ref:`compose.setComposeDetails` function for more information.
.. api-header:: :label: Required permissions - :permission:`compose`
.. api-section-annotation-hack:: -- [Added in TB 78]
Fired when an attachment is added to a message being composed.
.. api-header::
:label: Parameters for event listeners
.. api-member::
:name: ``tab``
:type: (:ref:`tabs.Tab`)
.. api-member::
:name: ``attachment``
:type: (:ref:`compose.ComposeAttachment`)
.. api-section-annotation-hack:: -- [Added in TB 78]
Fired when an attachment is removed from a message being composed.
.. api-header::
:label: Parameters for event listeners
.. api-member::
:name: ``tab``
:type: (:ref:`tabs.Tab`)
.. api-member::
:name: ``attachmentId``
:type: (integer)
.. api-section-annotation-hack:: -- [Added in TB 78.0b2]
Fired when the user changes the identity that will be used to send a message being composed.
.. api-header::
:label: Parameters for event listeners
.. api-member::
:name: ``tab``
:type: (:ref:`tabs.Tab`)
.. api-member::
:name: ``identityId``
:type: (string)
.. api-header:: :label: Required permissions - :permission:`accountsRead`
.. rst-class:: api-main-section
.. api-section-annotation-hack:: -- [Added in TB 78]
Represents an attachment in a message being composed.
.. api-header::
:label: object
.. api-member::
:name: ``id``
:type: (integer)
A unique identifier for this attachment.
.. api-member::
:name: ``name``
:type: (string)
The name, as displayed to the user, of this attachment. This is usually but not always the filename of the attached file.
.. api-member::
:name: ``size``
:type: (integer)
:annotation: -- [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.
.. api-section-annotation-hack::
Used by various functions to represent the state of a message being composed. Note that functions using this type may have a partial implementation.
.. api-header::
:label: object
.. api-member::
:name: [``attachments``]
:type: (array of object)
:annotation: -- [Added in TB 82, backported to TB 78.4.0]
Attachments to add to the message. Only used in the begin* functions.
.. api-member::
:name: [``bcc``]
:type: (:ref:`compose.ComposeRecipientList`)
.. api-member::
:name: [``body``]
:type: (string)
.. api-member::
:name: [``cc``]
:type: (:ref:`compose.ComposeRecipientList`)
.. api-member::
:name: [``followupTo``]
:type: (:ref:`compose.ComposeRecipientList`)
:annotation: -- [Added in TB 74]
.. api-member::
:name: [``identityId``]
:type: (string)
:annotation: -- [Added in TB 76]
The ID of an identity from the :doc:`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 :permission:`accountsRead` is required to include the ``identityId``.
.. api-member::
:name: [``isPlainText``]
:type: (boolean)
:annotation: -- [Added in TB 75]
.. api-member::
:name: [``newsgroups``]
:type: (string or array of string)
:annotation: -- [Added in TB 74]
.. api-member::
:name: [``plainTextBody``]
:type: (string)
:annotation: -- [Added in TB 75]
.. api-member::
:name: [``replyTo``]
:type: (:ref:`compose.ComposeRecipientList`)
.. api-member::
:name: [``subject``]
:type: (string)
.. api-member::
:name: [``to``]
:type: (:ref:`compose.ComposeRecipientList`)
.. api-section-annotation-hack::
.. api-header::
:label: string
.. container:: api-member-node
.. container:: api-member-description-only
A name and email address in the format "Name <email@example.com>", or just an email address.
OR
.. api-header::
:label: object
.. container:: api-member-node
.. container:: api-member-description-only
.. api-member::
:name: ``id``
:type: (string)
The ID of a contact or mailing list from the :doc:`contacts` and :doc:`mailingLists` APIs.
.. api-member::
:name: ``type``
:type: (`string`)
Which sort of object this ID is for.
Supported values:
.. api-member::
:name: ``contact``
.. api-member::
:name: ``mailingList``
.. api-section-annotation-hack:: -- [Added in TB 74]
.. api-header::
:label: string
.. container:: api-member-node
.. container:: api-member-description-only
A name and email address in the format "Name <email@example.com>", or just an email address.
OR
.. api-header:: :label: array of :ref:`compose.ComposeRecipient`