path: root/comm/mail/components/extensions/schemas/compose.json

[
  {
    "namespace": "manifest",
    "types": [
      {
        "$extend": "OptionalPermission",
        "choices": [
          {
            "type": "string",
            "enum": ["compose", "compose.save", "compose.send"]
          }
        ]
      }
    ]
  },
  {
    "namespace": "compose",
    "types": [
      {
        "id": "ComposeRecipient",
        "choices": [
          {
            "type": "string",
            "description": "A name and email address in the format <value>Name <email@example.com></value>, or just an email address."
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "The ID of a contact or mailing list from the :doc:`contacts` and :doc:`mailingLists` APIs."
              },
              "type": {
                "type": "string",
                "description": "Which sort of object this ID is for.",
                "enum": ["contact", "mailingList"]
              }
            }
          }
        ]
      },
      {
        "id": "ComposeRecipientList",
        "choices": [
          {
            "$ref": "ComposeRecipient"
          },
          {
            "type": "array",
            "items": {
              "$ref": "ComposeRecipient"
            }
          }
        ]
      },
      {
        "id": "ComposeState",
        "type": "object",
        "description": "Represent the state of the message composer.",
        "properties": {
          "canSendNow": {
            "type": "boolean",
            "description": "The message can be send now."
          },
          "canSendLater": {
            "type": "boolean",
            "description": "The message can be send later."
          }
        }
      },
      {
        "id": "ComposeDetails",
        "type": "object",
        "description": "Used by various functions to represent the state of a message being composed. Note that functions using this type may have a partial implementation.",
        "properties": {
          "identityId": {
            "type": "string",
            "description": "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</permission> is required to include the ``identityId``.",
            "optional": true
          },
          "from": {
            "$ref": "ComposeRecipient",
            "description": "*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.",
            "optional": true
          },
          "to": {
            "$ref": "ComposeRecipientList",
            "optional": true
          },
          "cc": {
            "$ref": "ComposeRecipientList",
            "optional": true
          },
          "bcc": {
            "$ref": "ComposeRecipientList",
            "optional": true
          },
          "overrideDefaultFcc": {
            "type": "boolean",
            "optional": true,
            "description": "Indicates whether the default fcc setting (defined by the used identity) is being overridden for this message. Setting <value>false</value> will clear the override. Setting <value>true</value> will throw an <em>ExtensionError</em>, if ``overrideDefaultFccFolder`` is not set as well."
          },
          "overrideDefaultFccFolder": {
            "choices": [
              {
                "$ref": "folders.MailFolder"
              },
              {
                "type": "string",
                "enum": [""]
              }
            ],
            "optional": true,
            "description": " This value overrides the default fcc setting (defined by the used identity) for this message only. Either a :ref:`folders.MailFolder` specifying the folder for the copy of the sent message, or an empty string to not save a copy at all."
          },
          "additionalFccFolder": {
            "choices": [
              {
                "$ref": "folders.MailFolder"
              },
              {
                "type": "string",
                "enum": [""]
              }
            ],
            "description": "An additional fcc folder which can be selected while composing the message, an empty string if not used.",
            "optional": true
          },
          "replyTo": {
            "$ref": "ComposeRecipientList",
            "optional": true
          },
          "followupTo": {
            "$ref": "ComposeRecipientList",
            "optional": true
          },
          "newsgroups": {
            "description": "A single newsgroup name or an array of newsgroup names.",
            "choices": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            ],
            "optional": true
          },
          "relatedMessageId": {
            "description": "The id of the original message (in case of draft, template, forward or reply). Read-only. Is <value>null</value> in all other cases or if the original message was opened from file.",
            "type": "integer",
            "optional": true
          },
          "subject": {
            "type": "string",
            "optional": true
          },
          "type": {
            "type": "string",
            "description": "Read-only. The type of the message being composed, depending on how the compose window was opened by the user.",
            "enum": ["draft", "new", "redirect", "reply", "forward"],
            "optional": true
          },
          "body": {
            "type": "string",
            "description": "The HTML content of the message.",
            "optional": true
          },
          "plainTextBody": {
            "type": "string",
            "description": "The plain text content of the message.",
            "optional": true
          },
          "isPlainText": {
            "type": "boolean",
            "description": "Whether the message is an HTML message or a plain text message.",
            "optional": true
          },
          "deliveryFormat": {
            "type": "string",
            "enum": ["auto", "plaintext", "html", "both"],
            "description": "Defines the mime format of the sent message (ignored on plain text messages). Defaults to <value>auto</value>, which will send html messages as plain text, if they do not include any formatting, and as <value>both</value> otherwise (a multipart/mixed message).",
            "optional": true
          },
          "customHeaders": {
            "type": "array",
            "items": {
              "$ref": "CustomHeader"
            },
            "description": "Array of custom headers. Headers will be returned in <em>Http-Header-Case</em> (a.k.a. <em>Train-Case</em>). Set an empty array to clear all custom headers.",
            "optional": true
          },
          "priority": {
            "type": "string",
            "enum": ["lowest", "low", "normal", "high", "highest"],
            "description": "The priority of the message.",
            "optional": true
          },
          "returnReceipt": {
            "type": "boolean",
            "optional": true,
            "description": "Add the <em>Disposition-Notification-To</em> 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."
          },
          "deliveryStatusNotification": {
            "type": "boolean",
            "optional": true,
            "description": "Let the sender know when the recipient's server received the message. Not supported by all servers."
          },
          "attachVCard": {
            "type": "boolean",
            "optional": true,
            "description": "Wether 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."
          },
          "attachments": {
            "type": "array",
            "items": {
              "choices": [
                {
                  "$ref": "FileAttachment"
                },
                {
                  "$ref": "ComposeAttachment"
                }
              ]
            },
            "description": "Only used in the begin* functions. Attachments to add to the message.",
            "optional": true
          }
        }
      },
      {
        "id": "FileAttachment",
        "type": "object",
        "description": "Object used to add, update or rename an attachment in a message being composed.",
        "properties": {
          "file": {
            "type": "object",
            "isInstanceOf": "File",
            "additionalProperties": true,
            "description": "The new content for the attachment.",
            "optional": true
          },
          "name": {
            "type": "string",
            "description": "The new name for the attachment, as displayed to the user. If not specified, the name of the provided ``file`` object is used.",
            "optional": true
          }
        }
      },
      {
        "id": "ComposeAttachment",
        "type": "object",
        "description": "Represents an attachment in a message being composed.",
        "properties": {
          "id": {
            "type": "integer",
            "description": "A unique identifier for this attachment."
          },
          "name": {
            "type": "string",
            "optional": true,
            "description": "The name of this attachment, as displayed to the user."
          },
          "size": {
            "type": "integer",
            "optional": true,
            "description": "The size in bytes of this attachment. Read-only."
          }
        }
      },
      {
        "id": "CustomHeader",
        "type": "object",
        "description": "A custom header definition.",
        "properties": {
          "name": {
            "type": "string",
            "description": "Name of a custom header, must have a <value>X-</value> prefix.",
            "pattern": "^X-.*$"
          },
          "value": {
            "type": "string"
          }
        }
      },
      {
        "id": "ComposeDictionaries",
        "type": "object",
        "additionalProperties": {
          "type": "boolean"
        },
        "description": "A <em>dictionary object</em> with entries for all installed dictionaries, having a language identifier as <em>key</em> (for example <value>en-US</value>) and a boolean expression as <em>value</em>, indicating whether that dictionary is enabled for spellchecking or not."
      }
    ],
    "events": [
      {
        "name": "onBeforeSend",
        "type": "function",
        "description": "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 <|link-user-input-restrictions|>`__ apply.",
        "permissions": ["compose"],
        "parameters": [
          {
            "name": "tab",
            "$ref": "tabs.Tab"
          },
          {
            "name": "details",
            "$ref": "ComposeDetails",
            "description": "The current state of the compose window. This is functionally the same as calling the :ref:`compose.getComposeDetails` function."
          }
        ],
        "returns": {
          "type": "object",
          "properties": {
            "cancel": {
              "type": "boolean",
              "optional": true,
              "description": "Cancels the send."
            },
            "details": {
              "$ref": "ComposeDetails",
              "optional": true,
              "description": "Updates the compose window. This is functionally the same as calling the :ref:`compose.setComposeDetails` function."
            }
          }
        }
      },
      {
        "name": "onAfterSend",
        "type": "function",
        "description": "Fired when sending a message succeeded or failed.",
        "permissions": ["compose"],
        "parameters": [
          {
            "name": "tab",
            "$ref": "tabs.Tab"
          },
          {
            "name": "sendInfo",
            "type": "object",
            "properties": {
              "mode": {
                "type": "string",
                "description": "The used send mode.",
                "enum": ["sendNow", "sendLater"]
              },
              "error": {
                "type": "string",
                "description": "An error description, if sending the message failed.",
                "optional": true
              },
              "headerMessageId": {
                "type": "string",
                "description": "The header messageId of the outgoing message. Only included for actually sent messages.",
                "optional": true
              },
              "messages": {
                "type": "array",
                "items": {
                  "$ref": "messages.MessageHeader"
                },
                "description": "Copies of the sent message. The number of created copies depends on the applied file carbon copy configuration (fcc)."
              }
            }
          }
        ]
      },
      {
        "name": "onAfterSave",
        "type": "function",
        "description": "Fired when saving a message as draft or template succeeded or failed.",
        "permissions": ["compose"],
        "parameters": [
          {
            "name": "tab",
            "$ref": "tabs.Tab"
          },
          {
            "name": "saveInfo",
            "type": "object",
            "properties": {
              "mode": {
                "type": "string",
                "description": "The used save mode.",
                "enum": ["draft", "template"]
              },
              "error": {
                "type": "string",
                "description": "An error description, if saving the message failed.",
                "optional": true
              },
              "messages": {
                "type": "array",
                "items": {
                  "$ref": "messages.MessageHeader"
                },
                "description": "The saved message(s). The number of saved messages depends on the applied file carbon copy configuration (fcc)."
              }
            }
          }
        ]
      },
      {
        "name": "onAttachmentAdded",
        "type": "function",
        "description": "Fired when an attachment is added to a message being composed.",
        "permissions": ["compose"],
        "parameters": [
          {
            "name": "tab",
            "$ref": "tabs.Tab"
          },
          {
            "name": "attachment",
            "$ref": "ComposeAttachment"
          }
        ]
      },
      {
        "name": "onAttachmentRemoved",
        "type": "function",
        "description": "Fired when an attachment is removed from a message being composed.",
        "permissions": ["compose"],
        "parameters": [
          {
            "name": "tab",
            "$ref": "tabs.Tab"
          },
          {
            "name": "attachmentId",
            "type": "integer"
          }
        ]
      },
      {
        "name": "onIdentityChanged",
        "type": "function",
        "description": "Fired when the user changes the identity that will be used to send a message being composed.",
        "permissions": ["accountsRead"],
        "parameters": [
          {
            "name": "tab",
            "$ref": "tabs.Tab"
          },
          {
            "name": "identityId",
            "type": "string"
          }
        ]
      },
      {
        "name": "onComposeStateChanged",
        "type": "function",
        "description": "Fired when the state of the message composer changed.",
        "parameters": [
          {
            "name": "tab",
            "$ref": "tabs.Tab"
          },
          {
            "name": "state",
            "$ref": "ComposeState"
          }
        ]
      },
      {
        "name": "onActiveDictionariesChanged",
        "type": "function",
        "description": "Fired when one or more dictionaries have been activated or deactivated.",
        "parameters": [
          {
            "name": "tab",
            "$ref": "tabs.Tab"
          },
          {
            "name": "dictionaries",
            "$ref": "ComposeDictionaries"
          }
        ]
      }
    ],
    "functions": [
      {
        "name": "beginNew",
        "type": "function",
        "description": "Open a new message compose window.\n\n**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.\n\n**Note:** Specifying ``details.body`` and ``details.plainTextBody`` without also specifying ``details.isPlainText`` threw an exception in Thunderbird up to version 97. Since Thunderbird 98, this combination creates a compose window with the compose format of the selected identity, using the matching ``details.body`` or ``details.plainTextBody`` value.\n\n**Note:** If no identity is specified, this function is using the default identity and not the identity of the referenced message.",
        "async": "callback",
        "parameters": [
          {
            "name": "messageId",
            "description": "If specified, the message or template to edit as a new message.",
            "type": "integer",
            "optional": true,
            "minimum": 1
          },
          {
            "name": "details",
            "$ref": "ComposeDetails",
            "optional": true
          },
          {
            "type": "function",
            "name": "callback",
            "optional": true,
            "parameters": [
              {
                "name": "return",
                "$ref": "tabs.Tab"
              }
            ]
          }
        ]
      },
      {
        "name": "beginReply",
        "type": "function",
        "description": "Open a new message compose window replying to a given message.\n\n**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.\n\n**Note:** Specifying ``details.body`` and ``details.plainTextBody`` without also specifying ``details.isPlainText`` threw an exception in Thunderbird up to version 97. Since Thunderbird 98, this combination creates a compose window with the compose format of the selected identity, using the matching ``details.body`` or ``details.plainTextBody`` value.\n\n**Note:** If no identity is specified, this function is using the default identity and not the identity of the referenced message.",
        "async": "callback",
        "parameters": [
          {
            "name": "messageId",
            "description": "The message to reply to, as retrieved using other APIs.",
            "type": "integer",
            "minimum": 1
          },
          {
            "name": "replyType",
            "type": "string",
            "enum": ["replyToSender", "replyToList", "replyToAll"],
            "optional": true
          },
          {
            "name": "details",
            "$ref": "ComposeDetails",
            "optional": true
          },
          {
            "type": "function",
            "name": "callback",
            "optional": true,
            "parameters": [
              {
                "name": "return",
                "$ref": "tabs.Tab"
              }
            ]
          }
        ]
      },
      {
        "name": "beginForward",
        "type": "function",
        "description": "Open a new message compose window forwarding a given message.\n\n**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.\n\n**Note:** Specifying ``details.body`` and ``details.plainTextBody`` without also specifying ``details.isPlainText`` threw an exception in Thunderbird up to version 97. Since Thunderbird 98, this combination creates a compose window with the compose format of the selected identity, using the matching ``details.body`` or ``details.plainTextBody`` value.\n\n**Note:** If no identity is specified, this function is using the default identity and not the identity of the referenced message.",
        "async": "callback",
        "parameters": [
          {
            "name": "messageId",
            "description": "The message to forward, as retrieved using other APIs.",
            "type": "integer",
            "minimum": 1
          },
          {
            "name": "forwardType",
            "type": "string",
            "enum": ["forwardInline", "forwardAsAttachment"],
            "optional": true
          },
          {
            "name": "details",
            "$ref": "ComposeDetails",
            "optional": true
          },
          {
            "type": "function",
            "name": "callback",
            "optional": true,
            "parameters": [
              {
                "name": "return",
                "$ref": "tabs.Tab"
              }
            ]
          }
        ]
      },
      {
        "name": "getComposeDetails",
        "type": "function",
        "async": "callback",
        "description": "Fetches the current state of a compose window. Currently only a limited amount of information is available, more will be added in later versions.",
        "permissions": ["compose"],
        "parameters": [
          {
            "type": "integer",
            "name": "tabId",
            "minimum": 0
          },
          {
            "type": "function",
            "name": "callback",
            "optional": true,
            "parameters": [
              {
                "$ref": "ComposeDetails"
              }
            ]
          }
        ]
      },
      {
        "name": "setComposeDetails",
        "type": "function",
        "async": true,
        "description": "Updates the compose window. The properties of the given :ref:`compose.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.\n\nWhen 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.\n\n**Note:** The compose format of an existing compose window cannot be changed. Since Thunderbird 98, setting conflicting values for ``details.body``, ``details.plainTextBody`` or ``details.isPlaintext`` no longer throws an exception, instead the compose window chooses the matching ``details.body`` or ``details.plainTextBody`` value and ignores the other.",
        "permissions": ["compose"],
        "parameters": [
          {
            "type": "integer",
            "name": "tabId",
            "minimum": 0
          },
          {
            "name": "details",
            "$ref": "ComposeDetails"
          }
        ]
      },
      {
        "name": "getActiveDictionaries",
        "type": "function",
        "async": "callback",
        "description": "Returns a :ref:`compose.ComposeDictionaries` object, listing all installed dictionaries, including the information whether they are currently enabled or not.",
        "permissions": ["compose"],
        "parameters": [
          {
            "type": "integer",
            "name": "tabId",
            "minimum": 0
          },
          {
            "type": "function",
            "name": "callback",
            "optional": true,
            "parameters": [
              {
                "$ref": "ComposeDictionaries"
              }
            ]
          }
        ]
      },
      {
        "name": "setActiveDictionaries",
        "type": "function",
        "async": true,
        "description": "Updates the active dictionaries. Throws if the ``activeDictionaries`` array contains unknown or invalid language identifiers.",
        "permissions": ["compose"],
        "parameters": [
          {
            "type": "integer",
            "name": "tabId",
            "minimum": 0
          },
          {
            "type": "array",
            "items": {
              "type": "string"
            },
            "name": "activeDictionaries"
          }
        ]
      },
      {
        "name": "listAttachments",
        "type": "function",
        "description": "Lists all of the attachments of the message being composed in the specified tab.",
        "permissions": ["compose"],
        "async": "callback",
        "parameters": [
          {
            "name": "tabId",
            "type": "integer"
          },
          {
            "type": "function",
            "name": "callback",
            "optional": true,
            "parameters": [
              {
                "type": "array",
                "items": {
                  "$ref": "ComposeAttachment"
                }
              }
            ]
          }
        ]
      },
      {
        "name": "getAttachmentFile",
        "type": "function",
        "description": "Gets the content of a :ref:`compose.ComposeAttachment` as a |File| object.",
        "async": "callback",
        "parameters": [
          {
            "name": "id",
            "type": "integer",
            "description": "The unique identifier for the attachment."
          },
          {
            "type": "function",
            "name": "callback",
            "optional": true,
            "parameters": [
              {
                "type": "object",
                "isInstanceOf": "File",
                "additionalProperties": true
              }
            ]
          }
        ]
      },
      {
        "name": "addAttachment",
        "type": "function",
        "description": "Adds an attachment to the message being composed in the specified tab.",
        "permissions": ["compose"],
        "async": "callback",
        "parameters": [
          {
            "name": "tabId",
            "type": "integer"
          },
          {
            "name": "attachment",
            "choices": [
              {
                "$ref": "FileAttachment"
              },
              {
                "$ref": "ComposeAttachment"
              }
            ]
          },
          {
            "type": "function",
            "name": "callback",
            "optional": true,
            "parameters": [
              {
                "$ref": "ComposeAttachment"
              }
            ]
          }
        ]
      },
      {
        "name": "updateAttachment",
        "type": "function",
        "description": "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 <em>ExtensionError</em>.",
        "permissions": ["compose"],
        "async": "callback",
        "parameters": [
          {
            "name": "tabId",
            "type": "integer"
          },
          {
            "name": "attachmentId",
            "type": "integer"
          },
          {
            "name": "attachment",
            "$ref": "FileAttachment"
          },
          {
            "type": "function",
            "name": "callback",
            "optional": true,
            "parameters": [
              {
                "$ref": "ComposeAttachment"
              }
            ]
          }
        ]
      },
      {
        "name": "removeAttachment",
        "type": "function",
        "description": "Removes an attachment from the message being composed in the specified tab.",
        "permissions": ["compose"],
        "async": true,
        "parameters": [
          {
            "name": "tabId",
            "type": "integer"
          },
          {
            "name": "attachmentId",
            "type": "integer"
          }
        ]
      },
      {
        "name": "sendMessage",
        "permissions": ["compose.send"],
        "type": "function",
        "description": "Sends the message currently being composed. If the send mode is not specified or set to <value>default</value>, 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 :ref:`compose.onBeforeSend` event or if there has been an error while sending the message to the outgoing mail server.",
        "async": "callback",
        "parameters": [
          {
            "name": "tabId",
            "type": "integer"
          },
          {
            "name": "options",
            "type": "object",
            "optional": true,
            "properties": {
              "mode": {
                "type": "string",
                "enum": ["default", "sendNow", "sendLater"]
              }
            }
          },
          {
            "type": "function",
            "name": "callback",
            "optional": true,
            "parameters": [
              {
                "name": "return",
                "type": "object",
                "properties": {
                  "mode": {
                    "type": "string",
                    "description": "The used send mode.",
                    "enum": ["sendNow", "sendLater"]
                  },
                  "headerMessageId": {
                    "type": "string",
                    "description": "The header messageId of the outgoing message. Only included for actually sent messages.",
                    "optional": true
                  },
                  "messages": {
                    "type": "array",
                    "items": {
                      "$ref": "messages.MessageHeader"
                    },
                    "description": "Copies of the sent message. The number of created copies depends on the applied file carbon copy configuration (fcc)."
                  }
                }
              }
            ]
          }
        ]
      },
      {
        "name": "saveMessage",
        "permissions": ["compose.save"],
        "type": "function",
        "description": "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.",
        "async": "callback",
        "parameters": [
          {
            "name": "tabId",
            "type": "integer"
          },
          {
            "name": "options",
            "type": "object",
            "optional": true,
            "properties": {
              "mode": {
                "type": "string",
                "enum": ["draft", "template"]
              }
            }
          },
          {
            "type": "function",
            "name": "callback",
            "optional": true,
            "parameters": [
              {
                "name": "return",
                "type": "object",
                "properties": {
                  "mode": {
                    "type": "string",
                    "description": "The used save mode.",
                    "enum": ["draft", "template"]
                  },
                  "messages": {
                    "type": "array",
                    "items": {
                      "$ref": "messages.MessageHeader"
                    },
                    "description": "The saved message(s). The number of saved messages depends on the applied file carbon copy configuration (fcc)."
                  }
                }
              }
            ]
          }
        ]
      },
      {
        "name": "getComposeState",
        "type": "function",
        "description": "Returns information about the current state of the message composer.",
        "async": "callback",
        "parameters": [
          {
            "name": "tabId",
            "type": "integer"
          },
          {
            "type": "function",
            "name": "callback",
            "optional": true,
            "parameters": [
              {
                "name": "return",
                "$ref": "ComposeState"
              }
            ]
          }
        ]
      }
    ]
  }
]