ark-email 0.6.0 → 0.8.0

data/rbi/ark_email/models/webhook_retrieve_delivery_response.rbi

@@ -0,0 +1,371 @@
+# typed: strong
+
+module ArkEmail
+  module Models
+    class WebhookRetrieveDeliveryResponse < ArkEmail::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(
+            ArkEmail::Models::WebhookRetrieveDeliveryResponse,
+            ArkEmail::Internal::AnyHash
+          )
+        end
+
+      # Full details of a webhook delivery including request and response
+      sig { returns(ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data) }
+      attr_reader :data
+
+      sig do
+        params(
+          data: ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::OrHash
+        ).void
+      end
+      attr_writer :data
+
+      sig { returns(ArkEmail::APIMeta) }
+      attr_reader :meta
+
+      sig { params(meta: ArkEmail::APIMeta::OrHash).void }
+      attr_writer :meta
+
+      sig { returns(T::Boolean) }
+      attr_accessor :success
+
+      # Detailed information about a webhook delivery attempt
+      sig do
+        params(
+          data: ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::OrHash,
+          meta: ArkEmail::APIMeta::OrHash,
+          success: T::Boolean
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # Full details of a webhook delivery including request and response
+        data:,
+        meta:,
+        success: true
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            data: ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data,
+            meta: ArkEmail::APIMeta,
+            success: T::Boolean
+          }
+        )
+      end
+      def to_hash
+      end
+
+      class Data < ArkEmail::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data,
+              ArkEmail::Internal::AnyHash
+            )
+          end
+
+        # Unique delivery ID (UUID)
+        sig { returns(String) }
+        attr_accessor :id
+
+        # Attempt number for this delivery
+        sig { returns(Integer) }
+        attr_accessor :attempt
+
+        # Event type that triggered this delivery
+        sig do
+          returns(
+            ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Event::TaggedSymbol
+          )
+        end
+        attr_accessor :event
+
+        # The request that was sent to your endpoint
+        sig do
+          returns(
+            ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Request
+          )
+        end
+        attr_reader :request
+
+        sig do
+          params(
+            request:
+              ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Request::OrHash
+          ).void
+        end
+        attr_writer :request
+
+        # The response received from your endpoint
+        sig do
+          returns(
+            ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Response
+          )
+        end
+        attr_reader :response
+
+        sig do
+          params(
+            response:
+              ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Response::OrHash
+          ).void
+        end
+        attr_writer :response
+
+        # HTTP status code returned by the endpoint
+        sig { returns(T.nilable(Integer)) }
+        attr_accessor :status_code
+
+        # Whether the delivery was successful (2xx response)
+        sig { returns(T::Boolean) }
+        attr_accessor :success
+
+        # When this delivery attempt occurred
+        sig { returns(Time) }
+        attr_accessor :timestamp
+
+        # URL the webhook was delivered to
+        sig { returns(String) }
+        attr_accessor :url
+
+        # ID of the webhook this delivery belongs to
+        sig { returns(String) }
+        attr_accessor :webhook_id
+
+        # Name of the webhook for easy identification
+        sig { returns(String) }
+        attr_accessor :webhook_name
+
+        # Whether this delivery will be retried
+        sig { returns(T::Boolean) }
+        attr_accessor :will_retry
+
+        # Full details of a webhook delivery including request and response
+        sig do
+          params(
+            id: String,
+            attempt: Integer,
+            event:
+              ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Event::OrSymbol,
+            request:
+              ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Request::OrHash,
+            response:
+              ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Response::OrHash,
+            status_code: T.nilable(Integer),
+            success: T::Boolean,
+            timestamp: Time,
+            url: String,
+            webhook_id: String,
+            webhook_name: String,
+            will_retry: T::Boolean
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          # Unique delivery ID (UUID)
+          id:,
+          # Attempt number for this delivery
+          attempt:,
+          # Event type that triggered this delivery
+          event:,
+          # The request that was sent to your endpoint
+          request:,
+          # The response received from your endpoint
+          response:,
+          # HTTP status code returned by the endpoint
+          status_code:,
+          # Whether the delivery was successful (2xx response)
+          success:,
+          # When this delivery attempt occurred
+          timestamp:,
+          # URL the webhook was delivered to
+          url:,
+          # ID of the webhook this delivery belongs to
+          webhook_id:,
+          # Name of the webhook for easy identification
+          webhook_name:,
+          # Whether this delivery will be retried
+          will_retry:
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              id: String,
+              attempt: Integer,
+              event:
+                ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Event::TaggedSymbol,
+              request:
+                ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Request,
+              response:
+                ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Response,
+              status_code: T.nilable(Integer),
+              success: T::Boolean,
+              timestamp: Time,
+              url: String,
+              webhook_id: String,
+              webhook_name: String,
+              will_retry: T::Boolean
+            }
+          )
+        end
+        def to_hash
+        end
+
+        # Event type that triggered this delivery
+        module Event
+          extend ArkEmail::Internal::Type::Enum
+
+          TaggedSymbol =
+            T.type_alias do
+              T.all(
+                Symbol,
+                ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Event
+              )
+            end
+          OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+          MESSAGE_SENT =
+            T.let(
+              :MessageSent,
+              ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Event::TaggedSymbol
+            )
+          MESSAGE_DELAYED =
+            T.let(
+              :MessageDelayed,
+              ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Event::TaggedSymbol
+            )
+          MESSAGE_DELIVERY_FAILED =
+            T.let(
+              :MessageDeliveryFailed,
+              ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Event::TaggedSymbol
+            )
+          MESSAGE_HELD =
+            T.let(
+              :MessageHeld,
+              ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Event::TaggedSymbol
+            )
+          MESSAGE_BOUNCED =
+            T.let(
+              :MessageBounced,
+              ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Event::TaggedSymbol
+            )
+          MESSAGE_LINK_CLICKED =
+            T.let(
+              :MessageLinkClicked,
+              ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Event::TaggedSymbol
+            )
+          MESSAGE_LOADED =
+            T.let(
+              :MessageLoaded,
+              ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Event::TaggedSymbol
+            )
+          DOMAIN_DNS_ERROR =
+            T.let(
+              :DomainDNSError,
+              ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Event::TaggedSymbol
+            )
+
+          sig do
+            override.returns(
+              T::Array[
+                ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Event::TaggedSymbol
+              ]
+            )
+          end
+          def self.values
+          end
+        end
+
+        class Request < ArkEmail::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Request,
+                ArkEmail::Internal::AnyHash
+              )
+            end
+
+          # HTTP headers that were sent with the request
+          sig { returns(T::Hash[Symbol, String]) }
+          attr_accessor :headers
+
+          # The complete webhook payload that was sent
+          sig { returns(T::Hash[Symbol, T.anything]) }
+          attr_accessor :payload
+
+          # The request that was sent to your endpoint
+          sig do
+            params(
+              headers: T::Hash[Symbol, String],
+              payload: T::Hash[Symbol, T.anything]
+            ).returns(T.attached_class)
+          end
+          def self.new(
+            # HTTP headers that were sent with the request
+            headers:,
+            # The complete webhook payload that was sent
+            payload:
+          )
+          end
+
+          sig do
+            override.returns(
+              {
+                headers: T::Hash[Symbol, String],
+                payload: T::Hash[Symbol, T.anything]
+              }
+            )
+          end
+          def to_hash
+          end
+        end
+
+        class Response < ArkEmail::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Response,
+                ArkEmail::Internal::AnyHash
+              )
+            end
+
+          # HTTP status code from your endpoint
+          sig { returns(T.nilable(Integer)) }
+          attr_accessor :status_code
+
+          # Response body from your endpoint (may be truncated)
+          sig { returns(T.nilable(String)) }
+          attr_accessor :body
+
+          # The response received from your endpoint
+          sig do
+            params(
+              status_code: T.nilable(Integer),
+              body: T.nilable(String)
+            ).returns(T.attached_class)
+          end
+          def self.new(
+            # HTTP status code from your endpoint
+            status_code:,
+            # Response body from your endpoint (may be truncated)
+            body: nil
+          )
+          end
+
+          sig do
+            override.returns(
+              { status_code: T.nilable(Integer), body: T.nilable(String) }
+            )
+          end
+          def to_hash
+          end
+        end
+      end
+    end
+  end
+end

data/rbi/ark_email/models.rbi

@@ -58,8 +58,15 @@ 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/rbi/ark_email/resources/emails.rbi

@@ -132,6 +132,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),
@@ -165,6 +166,25 @@ module ArkEmail
         # Body param: HTML body content (accepts null). Maximum 5MB (5,242,880
         # characters). Combined with attachments, the total message must not exceed 14MB.
         html: nil,
+        # Body param: 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,
         # Body param: Reply-to address (accepts null)
         reply_to: nil,
         # Body param: Tag for categorization and filtering (accepts null)
@@ -195,7 +215,7 @@ module ArkEmail
         ).returns(ArkEmail::Models::EmailSendBatchResponse)
       end
       def send_batch(
-        # Body param:
+        # Body param
         emails:,
         # Body param: Sender email for all messages
         from:,

data/rbi/ark_email/resources/webhooks.rbi

@@ -102,6 +102,111 @@ module ArkEmail
       def delete(webhook_id, request_options: {})
       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.
+      sig do
+        params(
+          webhook_id: String,
+          after: Integer,
+          before: Integer,
+          event: ArkEmail::WebhookListDeliveriesParams::Event::OrSymbol,
+          page: Integer,
+          per_page: Integer,
+          success: T::Boolean,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(ArkEmail::Models::WebhookListDeliveriesResponse)
+      end
+      def list_deliveries(
+        # Webhook ID or UUID
+        webhook_id,
+        # Only deliveries after this Unix timestamp
+        after: nil,
+        # Only deliveries before this Unix timestamp
+        before: nil,
+        # Filter by event type
+        event: nil,
+        # Page number (default 1)
+        page: nil,
+        # Items per page (default 30, max 100)
+        per_page: nil,
+        # Filter by delivery success (true = 2xx response, false = non-2xx or error)
+        success: nil,
+        request_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.
+      sig do
+        params(
+          delivery_id: String,
+          webhook_id: String,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(ArkEmail::Models::WebhookReplayDeliveryResponse)
+      end
+      def replay_delivery(
+        # Delivery ID (UUID) to replay
+        delivery_id,
+        # Webhook ID or UUID
+        webhook_id:,
+        request_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.
+      sig do
+        params(
+          delivery_id: String,
+          webhook_id: String,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(ArkEmail::Models::WebhookRetrieveDeliveryResponse)
+      end
+      def retrieve_delivery(
+        # Delivery ID (UUID)
+        delivery_id,
+        # Webhook ID or UUID
+        webhook_id:,
+        request_options: {}
+      )
+      end
+
       # Send a test payload to your webhook endpoint and verify it receives the data
       # correctly.
       #

data/sig/ark_email/models/email_send_batch_params.rbs

@@ -39,6 +39,7 @@ module ArkEmail
           subject: String,
           to: ::Array[String],
           html: String?,
+          metadata: ::Hash[Symbol, String]?,
           tag: String?,
           text: String?
         }
@@ -50,6 +51,8 @@ module ArkEmail
 
         attr_accessor html: String?
 
+        attr_accessor metadata: ::Hash[Symbol, String]?
+
         attr_accessor tag: String?
 
         attr_accessor text: String?
@@ -58,6 +61,7 @@ module ArkEmail
           subject: String,
           to: ::Array[String],
           ?html: String?,
+          ?metadata: ::Hash[Symbol, String]?,
           ?tag: String?,
           ?text: String?
         ) -> void
@@ -66,6 +70,7 @@ module ArkEmail
           subject: String,
           to: ::Array[String],
           html: String?,
+          metadata: ::Hash[Symbol, String]?,
           tag: String?,
           text: String?
         }

data/sig/ark_email/models/email_send_params.rbs

@@ -10,6 +10,7 @@ module ArkEmail
         cc: ::Array[String]?,
         headers: ::Hash[Symbol, String]?,
         html: String?,
+        metadata: ::Hash[Symbol, String]?,
         reply_to: String?,
         tag: String?,
         text: String?,
@@ -37,6 +38,8 @@ module ArkEmail
 
       attr_accessor html: String?
 
+      attr_accessor metadata: ::Hash[Symbol, String]?
+
       attr_accessor reply_to: String?
 
       attr_accessor tag: String?
@@ -56,6 +59,7 @@ module ArkEmail
         ?cc: ::Array[String]?,
         ?headers: ::Hash[Symbol, String]?,
         ?html: String?,
+        ?metadata: ::Hash[Symbol, String]?,
         ?reply_to: String?,
         ?tag: String?,
         ?text: String?,
@@ -72,6 +76,7 @@ module ArkEmail
         cc: ::Array[String]?,
         headers: ::Hash[Symbol, String]?,
         html: String?,
+        metadata: ::Hash[Symbol, String]?,
         reply_to: String?,
         tag: String?,
         text: String?,

data/sig/ark_email/models/webhook_list_deliveries_params.rbs

@@ -0,0 +1,90 @@
+module ArkEmail
+  module Models
+    type webhook_list_deliveries_params =
+      {
+        after: Integer,
+        before: Integer,
+        event: ArkEmail::Models::WebhookListDeliveriesParams::event,
+        page: Integer,
+        per_page: Integer,
+        success: bool
+      }
+      & ArkEmail::Internal::Type::request_parameters
+
+    class WebhookListDeliveriesParams < ArkEmail::Internal::Type::BaseModel
+      extend ArkEmail::Internal::Type::RequestParameters::Converter
+      include ArkEmail::Internal::Type::RequestParameters
+
+      attr_reader after: Integer?
+
+      def after=: (Integer) -> Integer
+
+      attr_reader before: Integer?
+
+      def before=: (Integer) -> Integer
+
+      attr_reader event: ArkEmail::Models::WebhookListDeliveriesParams::event?
+
+      def event=: (
+        ArkEmail::Models::WebhookListDeliveriesParams::event
+      ) -> ArkEmail::Models::WebhookListDeliveriesParams::event
+
+      attr_reader page: Integer?
+
+      def page=: (Integer) -> Integer
+
+      attr_reader per_page: Integer?
+
+      def per_page=: (Integer) -> Integer
+
+      attr_reader success: bool?
+
+      def success=: (bool) -> bool
+
+      def initialize: (
+        ?after: Integer,
+        ?before: Integer,
+        ?event: ArkEmail::Models::WebhookListDeliveriesParams::event,
+        ?page: Integer,
+        ?per_page: Integer,
+        ?success: bool,
+        ?request_options: ArkEmail::request_opts
+      ) -> void
+
+      def to_hash: -> {
+        after: Integer,
+        before: Integer,
+        event: ArkEmail::Models::WebhookListDeliveriesParams::event,
+        page: Integer,
+        per_page: Integer,
+        success: bool,
+        request_options: ArkEmail::RequestOptions
+      }
+
+      type event =
+        :MessageSent
+        | :MessageDelayed
+        | :MessageDeliveryFailed
+        | :MessageHeld
+        | :MessageBounced
+        | :MessageLinkClicked
+        | :MessageLoaded
+        | :DomainDNSError
+
+      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
+
+        def self?.values: -> ::Array[ArkEmail::Models::WebhookListDeliveriesParams::event]
+      end
+    end
+  end
+end