[OAS] Add examples for running an email connector (#170819)

elastic · Nov 11, 2023 · fa489d6 · fa489d6
1 parent b84881a
commit fa489d6
Show file tree

Hide file tree

Showing 9 changed files with 310 additions and 5 deletions.
diff --git a/docs/api/actions-and-connectors/execute.asciidoc b/docs/api/actions-and-connectors/execute.asciidoc
@@ -60,6 +60,32 @@ refer to <<action-types>>.
 [%collapsible%open]
 ====
 
+.Email connectors
+[%collapsible%open]
+=====
+`bcc`::
+(Optional, array of strings) A list of "blind carbon copy" email addresses.
+Addresses can be specified in `user@host-name` format or in name `<user@host-name>` format.
+
+`cc`::
+(Optional, array of strings) A list of "carbon copy" email addresses.
+Addresses can be specified in `user@host-name` format or in name `<user@host-name>` format.
+
+`message`::
+(Required, string) The email message text. Markdown format is supported.
+
+`subject`::
+(Required, string) The subject line of the email.
+
+`to`::
+(Required^*^, array of strings)
+A list of email addresses.
+Addresses can be specified in `user@host-name` format or in name `<user@host-name>` format.
+There must be at least one recipient in `to`, `cc`, or `bcc`.
+
+For more information, refer to <<email-action-type>>.
+=====
+
 .Index connectors
 [%collapsible%open]
 =====

diff --git a/x-pack/plugins/actions/docs/openapi/bundled.json b/x-pack/plugins/actions/docs/openapi/bundled.json
@@ -294,6 +294,9 @@
                 "$ref": "#/components/schemas/run_connector_request"
               },
               "examples": {
+                "runEmailConnectorRequest": {
+                  "$ref": "#/components/examples/run_email_connector_request"
+                },
                 "runIndexConnectorRequest": {
                   "$ref": "#/components/examples/run_index_connector_request"
                 },
@@ -356,6 +359,9 @@
                   }
                 },
                 "examples": {
+                  "runEmailConnectorResponse": {
+                    "$ref": "#/components/examples/run_email_connector_response"
+                  },
                   "runIndexConnectorResponse": {
                     "$ref": "#/components/examples/run_index_connector_response"
                   },
@@ -4770,7 +4776,66 @@
           }
         }
       },
-      "run_connector_params_level_message": {
+      "run_connector_params_message_email": {
+        "title": "Email connector parameters",
+        "description": "Test an action that sends an email message. There must be at least one recipient in `to`, `cc`, or `bcc`.\n",
+        "type": "object",
+        "anyOf": [
+          {
+            "required": [
+              "bcc",
+              "message",
+              "subject"
+            ]
+          },
+          {
+            "required": [
+              "cc",
+              "message",
+              "subject"
+            ]
+          },
+          {
+            "required": [
+              "to",
+              "message",
+              "subject"
+            ]
+          }
+        ],
+        "properties": {
+          "bcc": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "A list of \"blind carbon copy\" email addresses. Addresses can be specified in `user@host-name` format or in name `<user@host-name>` format\n"
+          },
+          "cc": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "A list of \"carbon copy\" email addresses. Addresses can be specified in `user@host-name` format or in name `<user@host-name>` format \n"
+          },
+          "message": {
+            "type": "string",
+            "description": "The email message text. Markdown format is supported."
+          },
+          "subject": {
+            "type": "string",
+            "description": "The subject line of the email."
+          },
+          "to": {
+            "type": "array",
+            "description": "A list of email addresses. Addresses can be specified in `user@host-name` format or in name `<user@host-name>` format.\n",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "run_connector_params_message_serverlog": {
         "title": "Server log connector parameters",
         "description": "Test an action that writes an entry to the Kibana server log.",
         "type": "object",
@@ -5448,7 +5513,10 @@
                 "$ref": "#/components/schemas/run_connector_params_documents"
               },
               {
-                "$ref": "#/components/schemas/run_connector_params_level_message"
+                "$ref": "#/components/schemas/run_connector_params_message_email"
+              },
+              {
+                "$ref": "#/components/schemas/run_connector_params_message_serverlog"
               },
               {
                 "title": "Subaction parameters",
@@ -5729,6 +5797,25 @@
           }
         }
       },
+      "run_email_connector_request": {
+        "summary": "Send an email message from an email connector.",
+        "value": {
+          "params": {
+            "bcc": [
+              "[email protected]"
+            ],
+            "cc": [
+              "[email protected]",
+              "[email protected]"
+            ],
+            "message": "Test email message.",
+            "subject": "Test message subject",
+            "to": [
+              "[email protected]"
+            ]
+          }
+        }
+      },
       "run_index_connector_request": {
         "summary": "Run an index connector.",
         "value": {
@@ -5795,6 +5882,36 @@
           }
         }
       },
+      "run_email_connector_response": {
+        "summary": "Response for sending a message from an email connector.",
+        "value": {
+          "connector_id": "7fc7b9a0-ecc9-11ec-8736-e7d63118c907",
+          "data": {
+            "accepted": [
+              "[email protected]",
+              "[email protected]",
+              "[email protected]",
+              "[email protected]"
+            ],
+            "envelope": {
+              "from": "[email protected]",
+              "to": [
+                "[email protected]",
+                "[email protected]",
+                "[email protected]",
+                "[email protected]"
+              ]
+            },
+            "envelopeTime": 8,
+            "messageTime": 3,
+            "messageSize": 729,
+            "response": "250 Message queued as QzEXKcGJ",
+            "messageId": "<[email protected]>",
+            "rejected": []
+          },
+          "status": "ok"
+        }
+      },
       "run_index_connector_response": {
         "summary": "Response from running an index connector.",
         "value": {

diff --git a/x-pack/plugins/actions/docs/openapi/bundled.yaml b/x-pack/plugins/actions/docs/openapi/bundled.yaml
@@ -179,6 +179,8 @@ paths:
             schema:
               $ref: '#/components/schemas/run_connector_request'
             examples:
+              runEmailConnectorRequest:
+                $ref: '#/components/examples/run_email_connector_request'
               runIndexConnectorRequest:
                 $ref: '#/components/examples/run_index_connector_request'
               runJiraConnectorRequest:
@@ -219,6 +221,8 @@ paths:
                       - error
                       - ok
               examples:
+                runEmailConnectorResponse:
+                  $ref: '#/components/examples/run_email_connector_response'
                 runIndexConnectorResponse:
                   $ref: '#/components/examples/run_index_connector_response'
                 runJiraConnectorResponse:
@@ -3345,7 +3349,50 @@ components:
           items:
             type: object
             additionalProperties: true
-    run_connector_params_level_message:
+    run_connector_params_message_email:
+      title: Email connector parameters
+      description: |
+        Test an action that sends an email message. There must be at least one recipient in `to`, `cc`, or `bcc`.
+      type: object
+      anyOf:
+        - required:
+            - bcc
+            - message
+            - subject
+        - required:
+            - cc
+            - message
+            - subject
+        - required:
+            - to
+            - message
+            - subject
+      properties:
+        bcc:
+          type: array
+          items:
+            type: string
+          description: |
+            A list of "blind carbon copy" email addresses. Addresses can be specified in `user@host-name` format or in name `<user@host-name>` format
+        cc:
+          type: array
+          items:
+            type: string
+          description: |
+            A list of "carbon copy" email addresses. Addresses can be specified in `user@host-name` format or in name `<user@host-name>` format 
+        message:
+          type: string
+          description: The email message text. Markdown format is supported.
+        subject:
+          type: string
+          description: The subject line of the email.
+        to:
+          type: array
+          description: |
+            A list of email addresses. Addresses can be specified in `user@host-name` format or in name `<user@host-name>` format.
+          items:
+            type: string
+    run_connector_params_message_serverlog:
       title: Server log connector parameters
       description: Test an action that writes an entry to the Kibana server log.
       type: object
@@ -3831,7 +3878,8 @@ components:
         params:
           oneOf:
             - $ref: '#/components/schemas/run_connector_params_documents'
-            - $ref: '#/components/schemas/run_connector_params_level_message'
+            - $ref: '#/components/schemas/run_connector_params_message_email'
+            - $ref: '#/components/schemas/run_connector_params_message_serverlog'
             - title: Subaction parameters
               description: Test an action that involves a subaction.
               oneOf:
@@ -4036,6 +4084,19 @@ components:
         name: updated-connector
         config:
           index: updated-index
+    run_email_connector_request:
+      summary: Send an email message from an email connector.
+      value:
+        params:
+          bcc:
+            - [email protected]
+          cc:
+            - [email protected]
+            - [email protected]
+          message: Test email message.
+          subject: Test message subject
+          to:
+            - [email protected]
     run_index_connector_request:
       summary: Run an index connector.
       value:
@@ -4077,6 +4138,30 @@ components:
               caseId: '1000'
               caseName: Case name
               description: Description of the incident.
+    run_email_connector_response:
+      summary: Response for sending a message from an email connector.
+      value:
+        connector_id: 7fc7b9a0-ecc9-11ec-8736-e7d63118c907
+        data:
+          accepted:
+            - [email protected]
+            - [email protected]
+            - [email protected]
+            - [email protected]
+          envelope:
+            from: [email protected]
+            to:
+              - [email protected]
+              - [email protected]
+              - [email protected]
+              - [email protected]
+          envelopeTime: 8
+          messageTime: 3
+          messageSize: 729
+          response: 250 Message queued as QzEXKcGJ
+          messageId: <[email protected]>
+          rejected: []
+        status: ok
     run_index_connector_response:
       summary: Response from running an index connector.
       value:

diff --git a/x-pack/plugins/actions/docs/openapi/components/examples/run_email_connector_request.yaml b/x-pack/plugins/actions/docs/openapi/components/examples/run_email_connector_request.yaml
@@ -0,0 +1,12 @@
+summary: Send an email message from an email connector.
+value:
+  params:
+    bcc:
+      - [email protected]
+    cc:
+      - [email protected]
+      - [email protected] 
+    message: Test email message.
+    subject: Test message subject
+    to:
+      - [email protected] 
diff --git a/x-pack/plugins/actions/docs/openapi/components/examples/run_email_connector_response.yaml b/x-pack/plugins/actions/docs/openapi/components/examples/run_email_connector_response.yaml
@@ -0,0 +1,23 @@
+summary: Response for sending a message from an email connector.
+value:
+  connector_id: 7fc7b9a0-ecc9-11ec-8736-e7d63118c907
+  data:
+    accepted:
+      - [email protected]
+      - [email protected]
+      - [email protected]
+      - [email protected]
+    envelope:
+      from: [email protected]
+      to:
+        - [email protected]
+        - [email protected]
+        - [email protected]
+        - [email protected]
+    envelopeTime: 8
+    messageTime: 3
+    messageSize: 729
+    response: "250 Message queued as QzEXKcGJ"
+    messageId: "<[email protected]>"
+    rejected: []
+  status: ok