ark-email 0.7.0 → 0.9.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

@@ -141,7 +141,8 @@ module ArkEmail
         ).returns(ArkEmail::Models::EmailSendResponse)
       end
       def send_(
-        # Body param: Sender email address. Must be from a verified domain.
+        # Body param: Sender email address. Must be from a verified domain OR use sandbox
+        # mode.
         #
         # **Supported formats:**
         #
@@ -150,6 +151,10 @@ module ArkEmail
         # - With quoted name: `"Acme Support" <support@yourdomain.com>`
         #
         # The domain portion must match a verified sending domain in your account.
+        #
+        # **Sandbox mode:** Use `sandbox@arkhq.io` to send test emails without domain
+        # verification. Sandbox emails can only be sent to organization members and are
+        # limited to 10 per day.
         from:,
         # Body param: Email subject line
         subject:,
@@ -176,6 +181,14 @@ module ArkEmail
         #
         # 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,

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_response.rbs

@@ -31,7 +31,8 @@ module ArkEmail
           accepted: Integer,
           failed: Integer,
           messages: ::Hash[Symbol, ArkEmail::Models::EmailSendBatchResponse::Data::Message],
-          total: Integer
+          total: Integer,
+          sandbox: bool
         }
 
       class Data < ArkEmail::Internal::Type::BaseModel
@@ -43,18 +44,24 @@ module ArkEmail
 
         attr_accessor total: Integer
 
+        attr_reader sandbox: bool?
+
+        def sandbox=: (bool) -> bool
+
         def initialize: (
           accepted: Integer,
           failed: Integer,
           messages: ::Hash[Symbol, ArkEmail::Models::EmailSendBatchResponse::Data::Message],
-          total: Integer
+          total: Integer,
+          ?sandbox: bool
         ) -> void
 
         def to_hash: -> {
           accepted: Integer,
           failed: Integer,
           messages: ::Hash[Symbol, ArkEmail::Models::EmailSendBatchResponse::Data::Message],
-          total: Integer
+          total: Integer,
+          sandbox: bool
         }
 
         type message = { id: String, token: String }

data/sig/ark_email/models/email_send_raw_response.rbs

@@ -31,7 +31,8 @@ module ArkEmail
           id: String,
           status: ArkEmail::Models::EmailSendRawResponse::Data::status,
           to: ::Array[String],
-          message_id: String
+          message_id: String,
+          sandbox: bool
         }
 
       class Data < ArkEmail::Internal::Type::BaseModel
@@ -45,18 +46,24 @@ module ArkEmail
 
         def message_id=: (String) -> String
 
+        attr_reader sandbox: bool?
+
+        def sandbox=: (bool) -> bool
+
         def initialize: (
           id: String,
           status: ArkEmail::Models::EmailSendRawResponse::Data::status,
           to: ::Array[String],
-          ?message_id: String
+          ?message_id: String,
+          ?sandbox: bool
         ) -> void
 
         def to_hash: -> {
           id: String,
           status: ArkEmail::Models::EmailSendRawResponse::Data::status,
           to: ::Array[String],
-          message_id: String
+          message_id: String,
+          sandbox: bool
         }
 
         type status = :pending | :sent

data/sig/ark_email/models/email_send_response.rbs

@@ -31,7 +31,8 @@ module ArkEmail
           id: String,
           status: ArkEmail::Models::EmailSendResponse::Data::status,
           to: ::Array[String],
-          message_id: String
+          message_id: String,
+          sandbox: bool
         }
 
       class Data < ArkEmail::Internal::Type::BaseModel
@@ -45,18 +46,24 @@ module ArkEmail
 
         def message_id=: (String) -> String
 
+        attr_reader sandbox: bool?
+
+        def sandbox=: (bool) -> bool
+
         def initialize: (
           id: String,
           status: ArkEmail::Models::EmailSendResponse::Data::status,
           to: ::Array[String],
-          ?message_id: String
+          ?message_id: String,
+          ?sandbox: bool
         ) -> void
 
         def to_hash: -> {
           id: String,
           status: ArkEmail::Models::EmailSendResponse::Data::status,
           to: ::Array[String],
-          message_id: String
+          message_id: String,
+          sandbox: bool
         }
 
         type status = :pending | :sent