Add OpenAPI spec for email transport webhook intake

examples/v2/email-transport/CreateEmailTransportWebhookIntake.rb

@@ -0,0 +1,86 @@
+# Ingest email transport webhook events returns "No Content" response
+
+require "datadog_api_client"
+DatadogAPIClient.configure do |config|
+  config.unstable_operations["v2.create_email_transport_webhook_intake".to_sym] = true
+end
+api_instance = DatadogAPIClient::V2::EmailTransportAPI.new
+
+body = [
+  DatadogAPIClient::V2::TransportWebhookLog.new({
+    attributes: DatadogAPIClient::V2::TransportWebhookLogAttributes.new({
+      category: [
+        "transactional",
+      ],
+      email: DatadogAPIClient::V2::TransportWebhookLogEmail.new({
+        address: "user@example.com",
+        domain: "example.com",
+        subject: "[Monitor Alert] CPU usage is high",
+        type: [
+          "transactional",
+        ],
+      }),
+      email_id: "abc123-def456",
+      email_type_display_name: "Monitor Alert",
+      message: DatadogAPIClient::V2::TransportWebhookLogMessage.new({
+        auth: DatadogAPIClient::V2::TransportWebhookLogMessageAuth.new({
+          delivered_with_tls: "TLSv1.2",
+        }),
+        custom_args: DatadogAPIClient::V2::TransportWebhookLogMessageCustomArgs.new({
+          email_id: "abc123-def456",
+          email_type_display_name: "Monitor Alert",
+          org_uuid: "8dee7c38-00cb-11ea-a77b-8b5a08d3b091",
+          queue_time: "2024-01-15T10:29:00Z",
+          subject: "[Monitor Alert] CPU usage is high",
+        }),
+        id: DatadogAPIClient::V2::TransportWebhookLogMessageId.new({
+          message_id: "<message-id@example.com>",
+          smtp_id: "<abc123@mail.example.com>",
+          transport_event_id: "evt_abc123",
+        }),
+        name: "delivered",
+        response: DatadogAPIClient::V2::TransportWebhookLogMessageResponse.new({
+          enhanced_smtp_code: "2.0.0",
+          reason: "250 2.0.0 OK",
+          smtp_code: "250",
+        }),
+        sender_ip: "192.168.1.1",
+        timestamp: DatadogAPIClient::V2::TransportWebhookLogMessageTimestamp.new({
+          event_timestamp: 1705312200.0,
+          lifetime: 3.2,
+          queue_time: 1.5,
+          scheduled_time: 1705312190.0,
+        }),
+      }),
+      network: DatadogAPIClient::V2::TransportWebhookLogNetwork.new({
+        ip: DatadogAPIClient::V2::TransportWebhookLogNetworkIp.new({
+          attributes: [
+            DatadogAPIClient::V2::TransportWebhookLogIpAttribute.new({
+              ip: "192.168.1.1",
+              source: [
+                "sendgrid",
+              ],
+            }),
+          ],
+          list: [
+            "192.168.1.1",
+          ],
+        }),
+      }),
+      org: 1234,
+      org_metadata: DatadogAPIClient::V2::TransportWebhookLogOrgMetadata.new({}),
+      org_uuid: "8dee7c38-00cb-11ea-a77b-8b5a08d3b091",
+      queue_time: "2024-01-15T10:29:00Z",
+      subject: "[Monitor Alert] CPU usage is high",
+      useragent: "Mozilla/5.0",
+    }),
+    date: "2024-01-15T10:30:00Z",
+    log_id: "AQAAAZPHnBT0TwJAdgAAAABBWlBIblVlNEFBQ0dFMmVkYTFDSnRR",
+    source: "sendgrid",
+    status: "info",
+    tags: [
+      "env:production",
+    ],
+  }),
+]
+api_instance.create_email_transport_webhook_intake(body)

features/scenarios_model_mapping.rb

@@ -2434,6 +2434,9 @@
             "page_offset" => "Integer",
             "page_limit" => "Integer",
     },
+    "v2.CreateEmailTransportWebhookIntake" => {
+            "body" => "Array<TransportWebhookLog>",
+    },
     "v2.SearchIssues" => {
             "include" => "Array<SearchIssuesIncludeQueryParameterItem>",
             "body" => "IssuesSearchRequest",

features/v2/email_transport.feature

@@ -0,0 +1,22 @@
+@endpoint(email-transport) @endpoint(email-transport-v2)
+Feature: Email Transport
+  Endpoints for receiving email transport webhook events for audit trail
+  processing.
+
+  Background:
+    Given a valid "apiKeyAuth" key in the system
+    And a valid "appKeyAuth" key in the system
+    And an instance of "EmailTransport" API
+    And operation "CreateEmailTransportWebhookIntake" enabled
+    And new "CreateEmailTransportWebhookIntake" request
+    And body with value [{"attributes": {"category": ["transactional"], "email": {"address": "user@example.com", "domain": "example.com", "subject": "[Monitor Alert] CPU usage is high", "type": ["transactional"]}, "email_id": "abc123-def456", "email_type_display_name": "Monitor Alert", "message": {"auth": {"delivered_with_tls": "TLSv1.2"}, "custom_args": {"email_id": "abc123-def456", "email_type_display_name": "Monitor Alert", "org_uuid": "8dee7c38-00cb-11ea-a77b-8b5a08d3b091", "queue_time": "2024-01-15T10:29:00Z", "subject": "[Monitor Alert] CPU usage is high"}, "id": {"message_id": "<message-id@example.com>", "smtp_id": "<abc123@mail.example.com>", "transport_event_id": "evt_abc123"}, "name": "delivered", "response": {"enhanced_smtp_code": "2.0.0", "reason": "250 2.0.0 OK", "smtp_code": "250"}, "sender_ip": "192.168.1.1", "timestamp": {"event_timestamp": 1705312200.0, "lifetime": 3.2, "queue_time": 1.5, "scheduled_time": 1705312190.0}}, "network": {"ip": {"attributes": [{"ip": "192.168.1.1", "source": ["sendgrid"]}], "list": ["192.168.1.1"]}}, "org": 1234, "org_metadata": {}, "org_uuid": "8dee7c38-00cb-11ea-a77b-8b5a08d3b091", "queue_time": "2024-01-15T10:29:00Z", "subject": "[Monitor Alert] CPU usage is high", "useragent": "Mozilla/5.0"}, "date": "2024-01-15T10:30:00Z", "log_id": "AQAAAZPHnBT0TwJAdgAAAABBWlBIblVlNEFBQ0dFMmVkYTFDSnRR", "source": "sendgrid", "status": "info", "tags": ["env:production"]}]
+
+  @generated @skip @team:DataDog/dogmail
+  Scenario: Ingest email transport webhook events returns "Bad Request" response
+    When the request is sent
+    Then the response status is 400 Bad Request
+
+  @generated @skip @team:DataDog/dogmail
+  Scenario: Ingest email transport webhook events returns "No Content" response
+    When the request is sent
+    Then the response status is 204 No Content

features/v2/undo.json

@@ -1863,6 +1863,12 @@
       "type": "idempotent"
     }
   },
+  "CreateEmailTransportWebhookIntake": {
+    "tag": "Email Transport",
+    "undo": {
+      "type": "safe"
+    }
+  },
   "SearchIssues": {
     "tag": "Error Tracking",
     "undo": {

lib/datadog_api_client/configuration.rb

@@ -317,6 +317,7 @@ def initialize
             "v2.trigger_deployment_gates_evaluation": false,
             "v2.update_deployment_gate": false,
             "v2.update_deployment_rule": false,
+            "v2.create_email_transport_webhook_intake": false,
             "v2.create_hamr_org_connection": false,
             "v2.get_hamr_org_connection": false,
             "v2.create_global_incident_handle": false,

lib/datadog_api_client/inflector.rb

@@ -6068,6 +6068,19 @@ def overrides
           "v2.timeseries_response_attributes" => "TimeseriesResponseAttributes",
           "v2.timeseries_response_series" => "TimeseriesResponseSeries",
           "v2.token_type" => "TokenType",
+          "v2.transport_webhook_log" => "TransportWebhookLog",
+          "v2.transport_webhook_log_attributes" => "TransportWebhookLogAttributes",
+          "v2.transport_webhook_log_email" => "TransportWebhookLogEmail",
+          "v2.transport_webhook_log_ip_attribute" => "TransportWebhookLogIpAttribute",
+          "v2.transport_webhook_log_message" => "TransportWebhookLogMessage",
+          "v2.transport_webhook_log_message_auth" => "TransportWebhookLogMessageAuth",
+          "v2.transport_webhook_log_message_custom_args" => "TransportWebhookLogMessageCustomArgs",
+          "v2.transport_webhook_log_message_id" => "TransportWebhookLogMessageId",
+          "v2.transport_webhook_log_message_response" => "TransportWebhookLogMessageResponse",
+          "v2.transport_webhook_log_message_timestamp" => "TransportWebhookLogMessageTimestamp",
+          "v2.transport_webhook_log_network" => "TransportWebhookLogNetwork",
+          "v2.transport_webhook_log_network_ip" => "TransportWebhookLogNetworkIp",
+          "v2.transport_webhook_log_org_metadata" => "TransportWebhookLogOrgMetadata",
           "v2.trigger" => "Trigger",
           "v2.trigger_attributes" => "TriggerAttributes",
           "v2.trigger_investigation_request" => "TriggerInvestigationRequest",
@@ -6412,6 +6425,7 @@ def overrides
         "v2.domain_allowlist_api" => "DomainAllowlistAPI",
         "v2.dora_metrics_api" => "DORAMetricsAPI",
         "v2.downtimes_api" => "DowntimesAPI",
+        "v2.email_transport_api" => "EmailTransportAPI",
         "v2.entity_risk_scores_api" => "EntityRiskScoresAPI",
         "v2.error_tracking_api" => "ErrorTrackingAPI",
         "v2.events_api" => "EventsAPI",

lib/datadog_api_client/v2/api/email_transport_api.rb

@@ -0,0 +1,101 @@
+=begin
+#Datadog API V2 Collection
+
+#Collection of all Datadog Public endpoints.
+
+The version of the OpenAPI document: 1.0
+Contact: support@datadoghq.com
+Generated by: https://github.com/DataDog/datadog-api-client-ruby/tree/master/.generator
+
+ Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
+ This product includes software developed at Datadog (https://www.datadoghq.com/).
+ Copyright 2020-Present Datadog, Inc.
+
+=end
+
+require 'cgi'
+
+module DatadogAPIClient::V2
+  class EmailTransportAPI
+    attr_accessor :api_client
+
+    def initialize(api_client = DatadogAPIClient::APIClient.default)
+      @api_client = api_client
+    end
+
+    # Ingest email transport webhook events.
+    #
+    # @see #create_email_transport_webhook_intake_with_http_info
+    def create_email_transport_webhook_intake(body, opts = {})
+      create_email_transport_webhook_intake_with_http_info(body, opts)
+      nil
+    end
+
+    # Ingest email transport webhook events.
+    #
+    # Receives a batch of email transport webhook log events and emits an audit trail entry
+    # for each event with a final delivery status (delivered, dropped, or bounced).
+    # Only authorized organizations can submit events.
+    #
+    # @param body [Array<TransportWebhookLog>] 
+    # @param opts [Hash] the optional parameters
+    # @return [Array<(nil, Integer, Hash)>] nil, response status code and response headers
+    def create_email_transport_webhook_intake_with_http_info(body, opts = {})
+      unstable_enabled = @api_client.config.unstable_operations["v2.create_email_transport_webhook_intake".to_sym]
+      if unstable_enabled
+        @api_client.config.logger.warn format("Using unstable operation '%s'", "v2.create_email_transport_webhook_intake")
+      else
+        raise DatadogAPIClient::APIError.new(message: format("Unstable operation '%s' is disabled", "v2.create_email_transport_webhook_intake"))
+      end
+
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: EmailTransportAPI.create_email_transport_webhook_intake ...'
+      end
+      # verify the required parameter 'body' is set
+      if @api_client.config.client_side_validation && body.nil?
+        fail ArgumentError, "Missing the required parameter 'body' when calling EmailTransportAPI.create_email_transport_webhook_intake"
+      end
+      # resource path
+      local_var_path = '/api/v2/email/transport/webhook_intake'
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['*/*'])
+      # HTTP header 'Content-Type'
+      header_params['Content-Type'] = @api_client.select_header_content_type(['application/json'])
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body] || @api_client.object_to_http_body(body)
+
+      # return_type
+      return_type = opts[:debug_return_type]
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || [:apiKeyAuth, :appKeyAuth]
+
+      new_options = opts.merge(
+        :operation => :create_email_transport_webhook_intake,
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type,
+        :api_version => "V2"
+      )
+
+      data, status_code, headers = @api_client.call_api(Net::HTTP::Post, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: EmailTransportAPI#create_email_transport_webhook_intake\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+  end
+end