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

@@ -144,7 +144,7 @@ module ArkEmail
       #
       # @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.
+      # @param from [String] Body param: Sender email address. Must be from a verified domain OR use sandbox
       #
       # @param subject [String] Body param: Email subject line
       #

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.7.0"
+  VERSION = "0.9.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

@@ -82,9 +82,18 @@ 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)
         sig { returns(T.nilable(T::Hash[Symbol, String])) }
         attr_accessor :metadata
 
+        # Tag for categorization and filtering
         sig { returns(T.nilable(String)) }
         attr_accessor :tag
 
@@ -115,7 +124,16 @@ 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,
+          # Tag for categorization and filtering
           tag: nil,
           text: nil
         )

data/rbi/ark_email/models/email_send_batch_response.rbi

@@ -84,6 +84,14 @@ module ArkEmail
         sig { returns(Integer) }
         attr_accessor :total
 
+        # Whether this batch was sent in sandbox mode. Only present (and true) for sandbox
+        # emails sent from @arkhq.io addresses.
+        sig { returns(T.nilable(T::Boolean)) }
+        attr_reader :sandbox
+
+        sig { params(sandbox: T::Boolean).void }
+        attr_writer :sandbox
+
         sig do
           params(
             accepted: Integer,
@@ -93,7 +101,8 @@ module ArkEmail
                 Symbol,
                 ArkEmail::Models::EmailSendBatchResponse::Data::Message::OrHash
               ],
-            total: Integer
+            total: Integer,
+            sandbox: T::Boolean
           ).returns(T.attached_class)
         end
         def self.new(
@@ -104,7 +113,10 @@ module ArkEmail
           # Map of recipient email to message info
           messages:,
           # Total emails in the batch
-          total:
+          total:,
+          # Whether this batch was sent in sandbox mode. Only present (and true) for sandbox
+          # emails sent from @arkhq.io addresses.
+          sandbox: nil
         )
         end
 
@@ -118,7 +130,8 @@ module ArkEmail
                   Symbol,
                   ArkEmail::Models::EmailSendBatchResponse::Data::Message
                 ],
-              total: Integer
+              total: Integer,
+              sandbox: T::Boolean
             }
           )
         end

data/rbi/ark_email/models/email_send_params.rbi

@@ -11,7 +11,7 @@ module ArkEmail
           T.any(ArkEmail::EmailSendParams, ArkEmail::Internal::AnyHash)
         end
 
-      # Sender email address. Must be from a verified domain.
+      # Sender email address. Must be from a verified domain OR use sandbox mode.
       #
       # **Supported formats:**
       #
@@ -20,6 +20,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.
       sig { returns(String) }
       attr_accessor :from
 
@@ -64,6 +68,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)
       sig { returns(T.nilable(T::Hash[Symbol, String])) }
       attr_accessor :metadata
 
@@ -106,7 +118,7 @@ module ArkEmail
         ).returns(T.attached_class)
       end
       def self.new(
-        # Sender email address. Must be from a verified domain.
+        # Sender email address. Must be from a verified domain OR use sandbox mode.
         #
         # **Supported formats:**
         #
@@ -115,6 +127,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:,
         # Email subject line
         subject:,
@@ -141,6 +157,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,
         # Reply-to address (accepts null)
         reply_to: nil,

data/rbi/ark_email/models/email_send_raw_response.rbi

@@ -82,13 +82,22 @@ module ArkEmail
         sig { params(message_id: String).void }
         attr_writer :message_id
 
+        # Whether this email was sent in sandbox mode. Only present (and true) for sandbox
+        # emails sent from @arkhq.io addresses.
+        sig { returns(T.nilable(T::Boolean)) }
+        attr_reader :sandbox
+
+        sig { params(sandbox: T::Boolean).void }
+        attr_writer :sandbox
+
         sig do
           params(
             id: String,
             status:
               ArkEmail::Models::EmailSendRawResponse::Data::Status::OrSymbol,
             to: T::Array[String],
-            message_id: String
+            message_id: String,
+            sandbox: T::Boolean
           ).returns(T.attached_class)
         end
         def self.new(
@@ -99,7 +108,10 @@ module ArkEmail
           # List of recipient addresses
           to:,
           # SMTP Message-ID header value
-          message_id: nil
+          message_id: nil,
+          # Whether this email was sent in sandbox mode. Only present (and true) for sandbox
+          # emails sent from @arkhq.io addresses.
+          sandbox: nil
         )
         end
 
@@ -110,7 +122,8 @@ module ArkEmail
               status:
                 ArkEmail::Models::EmailSendRawResponse::Data::Status::TaggedSymbol,
               to: T::Array[String],
-              message_id: String
+              message_id: String,
+              sandbox: T::Boolean
             }
           )
         end

data/rbi/ark_email/models/email_send_response.rbi

@@ -82,12 +82,21 @@ module ArkEmail
         sig { params(message_id: String).void }
         attr_writer :message_id
 
+        # Whether this email was sent in sandbox mode. Only present (and true) for sandbox
+        # emails sent from @arkhq.io addresses.
+        sig { returns(T.nilable(T::Boolean)) }
+        attr_reader :sandbox
+
+        sig { params(sandbox: T::Boolean).void }
+        attr_writer :sandbox
+
         sig do
           params(
             id: String,
             status: ArkEmail::Models::EmailSendResponse::Data::Status::OrSymbol,
             to: T::Array[String],
-            message_id: String
+            message_id: String,
+            sandbox: T::Boolean
           ).returns(T.attached_class)
         end
         def self.new(
@@ -98,7 +107,10 @@ module ArkEmail
           # List of recipient addresses
           to:,
           # SMTP Message-ID header value
-          message_id: nil
+          message_id: nil,
+          # Whether this email was sent in sandbox mode. Only present (and true) for sandbox
+          # emails sent from @arkhq.io addresses.
+          sandbox: nil
         )
         end
 
@@ -109,7 +121,8 @@ module ArkEmail
               status:
                 ArkEmail::Models::EmailSendResponse::Data::Status::TaggedSymbol,
               to: T::Array[String],
-              message_id: String
+              message_id: String,
+              sandbox: T::Boolean
             }
           )
         end