ark-email 0.6.0 → 0.8.0

data/lib/ark_email/models/webhook_retrieve_delivery_response.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module ArkEmail
+  module Models
+    # @see ArkEmail::Resources::Webhooks#retrieve_delivery
+    class WebhookRetrieveDeliveryResponse < ArkEmail::Internal::Type::BaseModel
+      # @!attribute data
+      #   Full details of a webhook delivery including request and response
+      #
+      #   @return [ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data]
+      required :data, -> { ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data }
+
+      # @!attribute meta
+      #
+      #   @return [ArkEmail::Models::APIMeta]
+      required :meta, -> { ArkEmail::APIMeta }
+
+      # @!attribute success
+      #
+      #   @return [Boolean, true]
+      required :success, const: true
+
+      # @!method initialize(data:, meta:, success: true)
+      #   Detailed information about a webhook delivery attempt
+      #
+      #   @param data [ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data] Full details of a webhook delivery including request and response
+      #
+      #   @param meta [ArkEmail::Models::APIMeta]
+      #
+      #   @param success [Boolean, true]
+
+      # @see ArkEmail::Models::WebhookRetrieveDeliveryResponse#data
+      class Data < ArkEmail::Internal::Type::BaseModel
+        # @!attribute id
+        #   Unique delivery ID (UUID)
+        #
+        #   @return [String]
+        required :id, String
+
+        # @!attribute attempt
+        #   Attempt number for this delivery
+        #
+        #   @return [Integer]
+        required :attempt, Integer
+
+        # @!attribute event
+        #   Event type that triggered this delivery
+        #
+        #   @return [Symbol, ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Event]
+        required :event, enum: -> { ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Event }
+
+        # @!attribute request
+        #   The request that was sent to your endpoint
+        #
+        #   @return [ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Request]
+        required :request, -> { ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Request }
+
+        # @!attribute response
+        #   The response received from your endpoint
+        #
+        #   @return [ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Response]
+        required :response, -> { ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Response }
+
+        # @!attribute status_code
+        #   HTTP status code returned by the endpoint
+        #
+        #   @return [Integer, nil]
+        required :status_code, Integer, api_name: :statusCode, nil?: true
+
+        # @!attribute success
+        #   Whether the delivery was successful (2xx response)
+        #
+        #   @return [Boolean]
+        required :success, ArkEmail::Internal::Type::Boolean
+
+        # @!attribute timestamp
+        #   When this delivery attempt occurred
+        #
+        #   @return [Time]
+        required :timestamp, Time
+
+        # @!attribute url
+        #   URL the webhook was delivered to
+        #
+        #   @return [String]
+        required :url, String
+
+        # @!attribute webhook_id
+        #   ID of the webhook this delivery belongs to
+        #
+        #   @return [String]
+        required :webhook_id, String, api_name: :webhookId
+
+        # @!attribute webhook_name
+        #   Name of the webhook for easy identification
+        #
+        #   @return [String]
+        required :webhook_name, String, api_name: :webhookName
+
+        # @!attribute will_retry
+        #   Whether this delivery will be retried
+        #
+        #   @return [Boolean]
+        required :will_retry, ArkEmail::Internal::Type::Boolean, api_name: :willRetry
+
+        # @!method initialize(id:, attempt:, event:, request:, response:, status_code:, success:, timestamp:, url:, webhook_id:, webhook_name:, will_retry:)
+        #   Full details of a webhook delivery including request and response
+        #
+        #   @param id [String] Unique delivery ID (UUID)
+        #
+        #   @param attempt [Integer] Attempt number for this delivery
+        #
+        #   @param event [Symbol, ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Event] Event type that triggered this delivery
+        #
+        #   @param request [ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Request] The request that was sent to your endpoint
+        #
+        #   @param response [ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Response] The response received from your endpoint
+        #
+        #   @param status_code [Integer, nil] HTTP status code returned by the endpoint
+        #
+        #   @param success [Boolean] Whether the delivery was successful (2xx response)
+        #
+        #   @param timestamp [Time] When this delivery attempt occurred
+        #
+        #   @param url [String] URL the webhook was delivered to
+        #
+        #   @param webhook_id [String] ID of the webhook this delivery belongs to
+        #
+        #   @param webhook_name [String] Name of the webhook for easy identification
+        #
+        #   @param will_retry [Boolean] Whether this delivery will be retried
+
+        # Event type that triggered this delivery
+        #
+        # @see ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data#event
+        module Event
+          extend ArkEmail::Internal::Type::Enum
+
+          MESSAGE_SENT = :MessageSent
+          MESSAGE_DELAYED = :MessageDelayed
+          MESSAGE_DELIVERY_FAILED = :MessageDeliveryFailed
+          MESSAGE_HELD = :MessageHeld
+          MESSAGE_BOUNCED = :MessageBounced
+          MESSAGE_LINK_CLICKED = :MessageLinkClicked
+          MESSAGE_LOADED = :MessageLoaded
+          DOMAIN_DNS_ERROR = :DomainDNSError
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
+
+        # @see ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data#request
+        class Request < ArkEmail::Internal::Type::BaseModel
+          # @!attribute headers
+          #   HTTP headers that were sent with the request
+          #
+          #   @return [Hash{Symbol=>String}]
+          required :headers, ArkEmail::Internal::Type::HashOf[String]
+
+          # @!attribute payload
+          #   The complete webhook payload that was sent
+          #
+          #   @return [Hash{Symbol=>Object}]
+          required :payload, ArkEmail::Internal::Type::HashOf[ArkEmail::Internal::Type::Unknown]
+
+          # @!method initialize(headers:, payload:)
+          #   The request that was sent to your endpoint
+          #
+          #   @param headers [Hash{Symbol=>String}] HTTP headers that were sent with the request
+          #
+          #   @param payload [Hash{Symbol=>Object}] The complete webhook payload that was sent
+        end
+
+        # @see ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data#response
+        class Response < ArkEmail::Internal::Type::BaseModel
+          # @!attribute status_code
+          #   HTTP status code from your endpoint
+          #
+          #   @return [Integer, nil]
+          required :status_code, Integer, api_name: :statusCode, nil?: true
+
+          # @!attribute body
+          #   Response body from your endpoint (may be truncated)
+          #
+          #   @return [String, nil]
+          optional :body, String, nil?: true
+
+          # @!method initialize(status_code:, body: nil)
+          #   The response received from your endpoint
+          #
+          #   @param status_code [Integer, nil] HTTP status code from your endpoint
+          #
+          #   @param body [String, nil] Response body from your endpoint (may be truncated)
+        end
+      end
+    end
+  end
+end

data/lib/ark_email/models.rb

@@ -95,8 +95,14 @@ module ArkEmail
 
   WebhookDeleteParams = ArkEmail::Models::WebhookDeleteParams
 
+  WebhookListDeliveriesParams = ArkEmail::Models::WebhookListDeliveriesParams
+
   WebhookListParams = ArkEmail::Models::WebhookListParams
 
+  WebhookReplayDeliveryParams = ArkEmail::Models::WebhookReplayDeliveryParams
+
+  WebhookRetrieveDeliveryParams = ArkEmail::Models::WebhookRetrieveDeliveryParams
+
   WebhookRetrieveParams = ArkEmail::Models::WebhookRetrieveParams
 
   WebhookTestParams = ArkEmail::Models::WebhookTestParams

data/lib/ark_email/resources/emails.rb

@@ -142,7 +142,7 @@ module ArkEmail
       # - `GET /emails/{id}/deliveries` - View delivery attempts
       # - `POST /emails/{id}/retry` - Retry failed delivery
       #
-      # @overload send_(from:, subject:, to:, attachments: nil, bcc: nil, cc: nil, headers: nil, html: nil, reply_to: nil, tag: nil, text: nil, idempotency_key: nil, request_options: {})
+      # @overload send_(from:, subject:, to:, attachments: nil, bcc: nil, cc: nil, headers: nil, html: nil, metadata: nil, reply_to: nil, tag: nil, text: nil, idempotency_key: nil, request_options: {})
       #
       # @param from [String] Body param: Sender email address. Must be from a verified domain.
       #
@@ -160,6 +160,8 @@ module ArkEmail
       #
       # @param html [String, nil] Body param: HTML body content (accepts null).
       #
+      # @param metadata [Hash{Symbol=>String}, nil] Body param: Custom key-value pairs attached to an email for webhook correlation.
+      #
       # @param reply_to [String, nil] Body param: Reply-to address (accepts null)
       #
       # @param tag [String, nil] Body param: Tag for categorization and filtering (accepts null)
@@ -199,7 +201,7 @@ module ArkEmail
       #
       # @overload send_batch(emails:, from:, idempotency_key: nil, request_options: {})
       #
-      # @param emails [Array<ArkEmail::Models::EmailSendBatchParams::Email>] Body param:
+      # @param emails [Array<ArkEmail::Models::EmailSendBatchParams::Email>] Body param
       #
       # @param from [String] Body param: Sender email for all messages
       #

data/lib/ark_email/resources/webhooks.rb

@@ -129,6 +129,133 @@ module ArkEmail
         )
       end
 
+      # Get a paginated list of delivery attempts for a specific webhook.
+      #
+      # Use this to:
+      #
+      # - Monitor webhook health and delivery success rate
+      # - Debug failed deliveries
+      # - Find specific events to replay
+      #
+      # **Filtering:**
+      #
+      # - Filter by success/failure to find problematic deliveries
+      # - Filter by event type to find specific events
+      # - Filter by time range for debugging recent issues
+      #
+      # **Retry behavior:** Failed deliveries are automatically retried with exponential
+      # backoff over ~3 days. Check `willRetry` to see if more attempts are scheduled.
+      #
+      # @overload list_deliveries(webhook_id, after: nil, before: nil, event: nil, page: nil, per_page: nil, success: nil, request_options: {})
+      #
+      # @param webhook_id [String] Webhook ID or UUID
+      #
+      # @param after [Integer] Only deliveries after this Unix timestamp
+      #
+      # @param before [Integer] Only deliveries before this Unix timestamp
+      #
+      # @param event [Symbol, ArkEmail::Models::WebhookListDeliveriesParams::Event] Filter by event type
+      #
+      # @param page [Integer] Page number (default 1)
+      #
+      # @param per_page [Integer] Items per page (default 30, max 100)
+      #
+      # @param success [Boolean] Filter by delivery success (true = 2xx response, false = non-2xx or error)
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::WebhookListDeliveriesResponse]
+      #
+      # @see ArkEmail::Models::WebhookListDeliveriesParams
+      def list_deliveries(webhook_id, params = {})
+        parsed, options = ArkEmail::WebhookListDeliveriesParams.dump_request(params)
+        @client.request(
+          method: :get,
+          path: ["webhooks/%1$s/deliveries", webhook_id],
+          query: parsed.transform_keys(per_page: "perPage"),
+          model: ArkEmail::Models::WebhookListDeliveriesResponse,
+          options: options
+        )
+      end
+
+      # Re-send a webhook delivery to your endpoint.
+      #
+      # **Use cases:**
+      #
+      # - Recover from transient failures after fixing your endpoint
+      # - Test endpoint changes with real historical data
+      # - Retry deliveries that failed due to downtime
+      #
+      # **How it works:**
+      #
+      # 1. Fetches the original payload from the delivery
+      # 2. Generates a new timestamp and signature
+      # 3. Sends to your webhook URL immediately
+      # 4. Returns the result (does not queue for retry if it fails)
+      #
+      # **Note:** The webhook must be enabled to replay deliveries.
+      #
+      # @overload replay_delivery(delivery_id, webhook_id:, request_options: {})
+      #
+      # @param delivery_id [String] Delivery ID (UUID) to replay
+      #
+      # @param webhook_id [String] Webhook ID or UUID
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::WebhookReplayDeliveryResponse]
+      #
+      # @see ArkEmail::Models::WebhookReplayDeliveryParams
+      def replay_delivery(delivery_id, params)
+        parsed, options = ArkEmail::WebhookReplayDeliveryParams.dump_request(params)
+        webhook_id =
+          parsed.delete(:webhook_id) do
+            raise ArgumentError.new("missing required path argument #{_1}")
+          end
+        @client.request(
+          method: :post,
+          path: ["webhooks/%1$s/deliveries/%2$s/replay", webhook_id, delivery_id],
+          model: ArkEmail::Models::WebhookReplayDeliveryResponse,
+          options: options
+        )
+      end
+
+      # Get detailed information about a specific webhook delivery attempt.
+      #
+      # Returns:
+      #
+      # - The complete request payload that was sent
+      # - Request headers including the signature
+      # - Response status code and body from your endpoint
+      # - Timing information
+      #
+      # Use this to debug why a delivery failed or verify what data was sent.
+      #
+      # @overload retrieve_delivery(delivery_id, webhook_id:, request_options: {})
+      #
+      # @param delivery_id [String] Delivery ID (UUID)
+      #
+      # @param webhook_id [String] Webhook ID or UUID
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::WebhookRetrieveDeliveryResponse]
+      #
+      # @see ArkEmail::Models::WebhookRetrieveDeliveryParams
+      def retrieve_delivery(delivery_id, params)
+        parsed, options = ArkEmail::WebhookRetrieveDeliveryParams.dump_request(params)
+        webhook_id =
+          parsed.delete(:webhook_id) do
+            raise ArgumentError.new("missing required path argument #{_1}")
+          end
+        @client.request(
+          method: :get,
+          path: ["webhooks/%1$s/deliveries/%2$s", webhook_id, delivery_id],
+          model: ArkEmail::Models::WebhookRetrieveDeliveryResponse,
+          options: options
+        )
+      end
+
       # Send a test payload to your webhook endpoint and verify it receives the data
       # correctly.
       #

data/lib/ark_email/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ArkEmail
-  VERSION = "0.6.0"
+  VERSION = "0.8.0"
 end

data/lib/ark_email.rb

@@ -106,8 +106,14 @@ require_relative "ark_email/models/webhook_create_params"
 require_relative "ark_email/models/webhook_create_response"
 require_relative "ark_email/models/webhook_delete_params"
 require_relative "ark_email/models/webhook_delete_response"
+require_relative "ark_email/models/webhook_list_deliveries_params"
+require_relative "ark_email/models/webhook_list_deliveries_response"
 require_relative "ark_email/models/webhook_list_params"
 require_relative "ark_email/models/webhook_list_response"
+require_relative "ark_email/models/webhook_replay_delivery_params"
+require_relative "ark_email/models/webhook_replay_delivery_response"
+require_relative "ark_email/models/webhook_retrieve_delivery_params"
+require_relative "ark_email/models/webhook_retrieve_delivery_response"
 require_relative "ark_email/models/webhook_retrieve_params"
 require_relative "ark_email/models/webhook_retrieve_response"
 require_relative "ark_email/models/webhook_test_params"

data/rbi/ark_email/models/email_send_batch_params.rbi

@@ -72,6 +72,28 @@ module ArkEmail
         sig { returns(T.nilable(String)) }
         attr_accessor :html
 
+        # Custom key-value pairs attached to an email for webhook correlation.
+        #
+        # When you send an email with metadata, these key-value pairs are:
+        #
+        # - **Stored** with the message
+        # - **Returned** in all webhook event payloads (MessageSent, MessageBounced, etc.)
+        # - **Never visible** to email recipients
+        #
+        # This is useful for correlating webhook events with your internal systems (e.g.,
+        # user IDs, order IDs, campaign identifiers).
+        #
+        # **Validation Rules:**
+        #
+        # - Maximum 10 keys per email
+        # - Keys: 1-40 characters, must start with a letter, only alphanumeric and
+        #   underscores (`^[a-zA-Z][a-zA-Z0-9_]*$`)
+        # - Values: 1-500 characters, no control characters (newlines, tabs, etc.)
+        # - Total size: 4KB maximum (JSON-encoded)
+        sig { returns(T.nilable(T::Hash[Symbol, String])) }
+        attr_accessor :metadata
+
+        # Tag for categorization and filtering
         sig { returns(T.nilable(String)) }
         attr_accessor :tag
 
@@ -83,11 +105,38 @@ module ArkEmail
             subject: String,
             to: T::Array[String],
             html: T.nilable(String),
+            metadata: T.nilable(T::Hash[Symbol, String]),
             tag: T.nilable(String),
             text: T.nilable(String)
           ).returns(T.attached_class)
         end
-        def self.new(subject:, to:, html: nil, tag: nil, text: nil)
+        def self.new(
+          subject:,
+          to:,
+          html: nil,
+          # Custom key-value pairs attached to an email for webhook correlation.
+          #
+          # When you send an email with metadata, these key-value pairs are:
+          #
+          # - **Stored** with the message
+          # - **Returned** in all webhook event payloads (MessageSent, MessageBounced, etc.)
+          # - **Never visible** to email recipients
+          #
+          # This is useful for correlating webhook events with your internal systems (e.g.,
+          # user IDs, order IDs, campaign identifiers).
+          #
+          # **Validation Rules:**
+          #
+          # - Maximum 10 keys per email
+          # - Keys: 1-40 characters, must start with a letter, only alphanumeric and
+          #   underscores (`^[a-zA-Z][a-zA-Z0-9_]*$`)
+          # - Values: 1-500 characters, no control characters (newlines, tabs, etc.)
+          # - Total size: 4KB maximum (JSON-encoded)
+          metadata: nil,
+          # Tag for categorization and filtering
+          tag: nil,
+          text: nil
+        )
         end
 
         sig do
@@ -96,6 +145,7 @@ module ArkEmail
               subject: String,
               to: T::Array[String],
               html: T.nilable(String),
+              metadata: T.nilable(T::Hash[Symbol, String]),
               tag: T.nilable(String),
               text: T.nilable(String)
             }

data/rbi/ark_email/models/email_send_params.rbi

@@ -54,6 +54,27 @@ module ArkEmail
       sig { returns(T.nilable(String)) }
       attr_accessor :html
 
+      # Custom key-value pairs attached to an email for webhook correlation.
+      #
+      # When you send an email with metadata, these key-value pairs are:
+      #
+      # - **Stored** with the message
+      # - **Returned** in all webhook event payloads (MessageSent, MessageBounced, etc.)
+      # - **Never visible** to email recipients
+      #
+      # This is useful for correlating webhook events with your internal systems (e.g.,
+      # user IDs, order IDs, campaign identifiers).
+      #
+      # **Validation Rules:**
+      #
+      # - Maximum 10 keys per email
+      # - Keys: 1-40 characters, must start with a letter, only alphanumeric and
+      #   underscores (`^[a-zA-Z][a-zA-Z0-9_]*$`)
+      # - Values: 1-500 characters, no control characters (newlines, tabs, etc.)
+      # - Total size: 4KB maximum (JSON-encoded)
+      sig { returns(T.nilable(T::Hash[Symbol, String])) }
+      attr_accessor :metadata
+
       # Reply-to address (accepts null)
       sig { returns(T.nilable(String)) }
       attr_accessor :reply_to
@@ -84,6 +105,7 @@ module ArkEmail
           cc: T.nilable(T::Array[String]),
           headers: T.nilable(T::Hash[Symbol, String]),
           html: T.nilable(String),
+          metadata: T.nilable(T::Hash[Symbol, String]),
           reply_to: T.nilable(String),
           tag: T.nilable(String),
           text: T.nilable(String),
@@ -117,6 +139,25 @@ module ArkEmail
         # HTML body content (accepts null). Maximum 5MB (5,242,880 characters). Combined
         # with attachments, the total message must not exceed 14MB.
         html: nil,
+        # Custom key-value pairs attached to an email for webhook correlation.
+        #
+        # When you send an email with metadata, these key-value pairs are:
+        #
+        # - **Stored** with the message
+        # - **Returned** in all webhook event payloads (MessageSent, MessageBounced, etc.)
+        # - **Never visible** to email recipients
+        #
+        # This is useful for correlating webhook events with your internal systems (e.g.,
+        # user IDs, order IDs, campaign identifiers).
+        #
+        # **Validation Rules:**
+        #
+        # - Maximum 10 keys per email
+        # - Keys: 1-40 characters, must start with a letter, only alphanumeric and
+        #   underscores (`^[a-zA-Z][a-zA-Z0-9_]*$`)
+        # - Values: 1-500 characters, no control characters (newlines, tabs, etc.)
+        # - Total size: 4KB maximum (JSON-encoded)
+        metadata: nil,
         # Reply-to address (accepts null)
         reply_to: nil,
         # Tag for categorization and filtering (accepts null)
@@ -141,6 +182,7 @@ module ArkEmail
             cc: T.nilable(T::Array[String]),
             headers: T.nilable(T::Hash[Symbol, String]),
             html: T.nilable(String),
+            metadata: T.nilable(T::Hash[Symbol, String]),
             reply_to: T.nilable(String),
             tag: T.nilable(String),
             text: T.nilable(String),