ark-email 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ddf19df44b85deecef1d6cbf6590336a3309035c29a4407967df568b5ac9ca19
-  data.tar.gz: d7048ca3b1397cd9c1ff148be90bb0bc24bcb691d543f511f8c94a7e9e6e3109
+  metadata.gz: 5b28db2b8003c270a67cebc743ea403628c8a13a8d0cff4b4e357704aae84c55
+  data.tar.gz: 8ccf63ab298517800021888ab0e2041d4eb5b66c27735d16e3ed2c630fb3eab7
 SHA512:
-  metadata.gz: 1d9d815fed0a695d07f4fc015c0b05e9864dbbdbe7f905566032eef3f13eee959276aa7b4abe256eaa668b73c4b690f7e94e5cef31c8ad4bedef0bfeb0ef7ae0
-  data.tar.gz: 45de3d27d11501f0430b2f32ee215bea62af5884e1a3c2507a36d6e833b734e22d3f6b3cb2f9de3a208225adce8546f50087fa54e78fde260fcbf9a1c9381854
+  metadata.gz: ebe864f749bc491e0d8d190661a3c265050b59d7a21e7e8bf97b4fb52c148040a02b42f51d03e7f5b2e19119c75abf1581ab78835d66529632453b4a206a7064
+  data.tar.gz: 0bd1b269b07c48c3514ec03cb0a7372c980f8f4ee48687b06c8bb7593cd2ea0303d6b22aa7bbc8300462294bd2132cf0232e87b585376a0f96470040941591c9

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.8.0 (2026-01-20)
+
+Full Changelog: [v0.7.0...v0.8.0](https://github.com/ArkHQ-io/ark-ruby/compare/v0.7.0...v0.8.0)
+
+### Features
+
+* **api:** add webhook deliveries ([bf74654](https://github.com/ArkHQ-io/ark-ruby/commit/bf746548583f88e32cac7cc8875388c7222b581a))
+* **api:** api update ([4218931](https://github.com/ArkHQ-io/ark-ruby/commit/42189310508e7607e2447dd93c15b510ca70ea0f))
+* **api:** api update ([81372c5](https://github.com/ArkHQ-io/ark-ruby/commit/81372c535c36671ff15d83309a88c5108f3d2115))
+* **api:** manual updates ([3934561](https://github.com/ArkHQ-io/ark-ruby/commit/3934561e4a5c942d344349d637471c36829ac318))
+
+
+### Chores
+
+* **internal:** update `actions/checkout` version ([45fbb7d](https://github.com/ArkHQ-io/ark-ruby/commit/45fbb7d77eff7f081c44e2174711183c7113a5df))
+
 ## 0.7.0 (2026-01-14)
 
 Full Changelog: [v0.6.0...v0.7.0](https://github.com/ArkHQ-io/ark-ruby/compare/v0.6.0...v0.7.0)

data/README.md

@@ -26,7 +26,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "ark-email", "~> 0.7.0"
+gem "ark-email", "~> 0.8.0"
 ```
 
 <!-- x-release-please-end -->
@@ -45,7 +45,9 @@ response = ark.emails.send_(
   from: "hello@yourdomain.com",
   subject: "Hello World",
   to: ["user@example.com"],
-  html: "<h1>Welcome!</h1>"
+  html: "<h1>Welcome!</h1>",
+  metadata: {user_id: "usr_123", campaign: "onboarding"},
+  tag: "welcome"
 )
 
 puts(response.data)
@@ -89,7 +91,9 @@ begin
     from: "hello@yourdomain.com",
     subject: "Hello World",
     to: ["user@example.com"],
-    html: "<h1>Welcome!</h1>"
+    html: "<h1>Welcome!</h1>",
+    metadata: {user_id: "usr_123", campaign: "onboarding"},
+    tag: "welcome"
   )
 rescue ArkEmail::Errors::APIConnectionError => e
   puts("The server could not be reached")
@@ -138,6 +142,8 @@ ark.emails.send_(
   subject: "Hello World",
   to: ["user@example.com"],
   html: "<h1>Welcome!</h1>",
+  metadata: {user_id: "usr_123", campaign: "onboarding"},
+  tag: "welcome",
   request_options: {max_retries: 5}
 )
 ```
@@ -158,6 +164,8 @@ ark.emails.send_(
   subject: "Hello World",
   to: ["user@example.com"],
   html: "<h1>Welcome!</h1>",
+  metadata: {user_id: "usr_123", campaign: "onboarding"},
+  tag: "welcome",
   request_options: {timeout: 5}
 )
 ```
@@ -195,6 +203,8 @@ response =
     subject: "Hello World",
     to: ["user@example.com"],
     html: "<h1>Welcome!</h1>",
+    metadata: {user_id: "usr_123", campaign: "onboarding"},
+    tag: "welcome",
     request_options: {
       extra_query: {my_query_parameter: value},
       extra_body: {my_body_parameter: value},
@@ -244,7 +254,9 @@ ark.emails.send_(
   from: "hello@yourdomain.com",
   subject: "Hello World",
   to: ["user@example.com"],
-  html: "<h1>Welcome!</h1>"
+  html: "<h1>Welcome!</h1>",
+  metadata: {user_id: "usr_123", campaign: "onboarding"},
+  tag: "welcome"
 )
 ```
 
@@ -256,7 +268,9 @@ ark.emails.send_(
   from: "hello@yourdomain.com",
   subject: "Hello World",
   to: ["user@example.com"],
-  html: "<h1>Welcome!</h1>"
+  html: "<h1>Welcome!</h1>",
+  metadata: {user_id: "usr_123", campaign: "onboarding"},
+  tag: "welcome"
 )
 
 # You can also splat a full Params class:
@@ -264,7 +278,9 @@ params = ArkEmail::EmailSendParams.new(
   from: "hello@yourdomain.com",
   subject: "Hello World",
   to: ["user@example.com"],
-  html: "<h1>Welcome!</h1>"
+  html: "<h1>Welcome!</h1>",
+  metadata: {user_id: "usr_123", campaign: "onboarding"},
+  tag: "welcome"
 )
 ark.emails.send_(**params)
 ```

data/lib/ark_email/models/email_send_batch_params.rb

@@ -60,10 +60,19 @@ 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)
+        #
         #   @return [Hash{Symbol=>String}, nil]
         optional :metadata, ArkEmail::Internal::Type::HashOf[String], nil?: true
 
         # @!attribute tag
+        #   Tag for categorization and filtering
         #
         #   @return [String, nil]
         optional :tag, String, nil?: true
@@ -85,7 +94,7 @@ module ArkEmail
         #
         #   @param metadata [Hash{Symbol=>String}, nil] Custom key-value pairs attached to an email for webhook correlation.
         #
-        #   @param tag [String, nil]
+        #   @param tag [String, nil] Tag for categorization and filtering
         #
         #   @param text [String, nil]
       end

data/lib/ark_email/models/email_send_params.rb

@@ -78,6 +78,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)
+      #
       #   @return [Hash{Symbol=>String}, nil]
       optional :metadata, ArkEmail::Internal::Type::HashOf[String], nil?: true
 

data/lib/ark_email/models/webhook_list_deliveries_params.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module ArkEmail
+  module Models
+    # @see ArkEmail::Resources::Webhooks#list_deliveries
+    class WebhookListDeliveriesParams < ArkEmail::Internal::Type::BaseModel
+      extend ArkEmail::Internal::Type::RequestParameters::Converter
+      include ArkEmail::Internal::Type::RequestParameters
+
+      # @!attribute after
+      #   Only deliveries after this Unix timestamp
+      #
+      #   @return [Integer, nil]
+      optional :after, Integer
+
+      # @!attribute before
+      #   Only deliveries before this Unix timestamp
+      #
+      #   @return [Integer, nil]
+      optional :before, Integer
+
+      # @!attribute event
+      #   Filter by event type
+      #
+      #   @return [Symbol, ArkEmail::Models::WebhookListDeliveriesParams::Event, nil]
+      optional :event, enum: -> { ArkEmail::WebhookListDeliveriesParams::Event }
+
+      # @!attribute page
+      #   Page number (default 1)
+      #
+      #   @return [Integer, nil]
+      optional :page, Integer
+
+      # @!attribute per_page
+      #   Items per page (default 30, max 100)
+      #
+      #   @return [Integer, nil]
+      optional :per_page, Integer
+
+      # @!attribute success
+      #   Filter by delivery success (true = 2xx response, false = non-2xx or error)
+      #
+      #   @return [Boolean, nil]
+      optional :success, ArkEmail::Internal::Type::Boolean
+
+      # @!method initialize(after: nil, before: nil, event: nil, page: nil, per_page: nil, success: nil, request_options: {})
+      #   @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}]
+
+      # Filter by event type
+      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
+    end
+  end
+end

data/lib/ark_email/models/webhook_list_deliveries_response.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module ArkEmail
+  module Models
+    # @see ArkEmail::Resources::Webhooks#list_deliveries
+    class WebhookListDeliveriesResponse < ArkEmail::Internal::Type::BaseModel
+      # @!attribute data
+      #
+      #   @return [Array<ArkEmail::Models::WebhookListDeliveriesResponse::Data>]
+      required :data,
+               -> { ArkEmail::Internal::Type::ArrayOf[ArkEmail::Models::WebhookListDeliveriesResponse::Data] }
+
+      # @!attribute meta
+      #
+      #   @return [ArkEmail::Models::APIMeta]
+      required :meta, -> { ArkEmail::APIMeta }
+
+      # @!attribute page
+      #   Current page number
+      #
+      #   @return [Integer]
+      required :page, Integer
+
+      # @!attribute per_page
+      #   Items per page
+      #
+      #   @return [Integer]
+      required :per_page, Integer, api_name: :perPage
+
+      # @!attribute total
+      #   Total number of deliveries matching the filter
+      #
+      #   @return [Integer]
+      required :total, Integer
+
+      # @!attribute total_pages
+      #   Total number of pages
+      #
+      #   @return [Integer]
+      required :total_pages, Integer, api_name: :totalPages
+
+      # @!method initialize(data:, meta:, page:, per_page:, total:, total_pages:)
+      #   Paginated list of webhook delivery attempts
+      #
+      #   @param data [Array<ArkEmail::Models::WebhookListDeliveriesResponse::Data>]
+      #
+      #   @param meta [ArkEmail::Models::APIMeta]
+      #
+      #   @param page [Integer] Current page number
+      #
+      #   @param per_page [Integer] Items per page
+      #
+      #   @param total [Integer] Total number of deliveries matching the filter
+      #
+      #   @param total_pages [Integer] Total number of pages
+
+      class Data < ArkEmail::Internal::Type::BaseModel
+        # @!attribute id
+        #   Unique delivery ID (UUID)
+        #
+        #   @return [String]
+        required :id, String
+
+        # @!attribute attempt
+        #   Attempt number (1 for first attempt, increments with retries)
+        #
+        #   @return [Integer]
+        required :attempt, Integer
+
+        # @!attribute event
+        #   Event type that triggered this delivery
+        #
+        #   @return [Symbol, ArkEmail::Models::WebhookListDeliveriesResponse::Data::Event]
+        required :event, enum: -> { ArkEmail::Models::WebhookListDeliveriesResponse::Data::Event }
+
+        # @!attribute status_code
+        #   HTTP status code returned by the endpoint (null if connection failed)
+        #
+        #   @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 will_retry
+        #   Whether this delivery will be retried (true if failed and retries remaining)
+        #
+        #   @return [Boolean]
+        required :will_retry, ArkEmail::Internal::Type::Boolean, api_name: :willRetry
+
+        # @!method initialize(id:, attempt:, event:, status_code:, success:, timestamp:, url:, webhook_id:, will_retry:)
+        #   Summary of a webhook delivery attempt
+        #
+        #   @param id [String] Unique delivery ID (UUID)
+        #
+        #   @param attempt [Integer] Attempt number (1 for first attempt, increments with retries)
+        #
+        #   @param event [Symbol, ArkEmail::Models::WebhookListDeliveriesResponse::Data::Event] Event type that triggered this delivery
+        #
+        #   @param status_code [Integer, nil] HTTP status code returned by the endpoint (null if connection failed)
+        #
+        #   @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 will_retry [Boolean] Whether this delivery will be retried (true if failed and retries remaining)
+
+        # Event type that triggered this delivery
+        #
+        # @see ArkEmail::Models::WebhookListDeliveriesResponse::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
+      end
+    end
+  end
+end

data/lib/ark_email/models/webhook_replay_delivery_params.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ArkEmail
+  module Models
+    # @see ArkEmail::Resources::Webhooks#replay_delivery
+    class WebhookReplayDeliveryParams < ArkEmail::Internal::Type::BaseModel
+      extend ArkEmail::Internal::Type::RequestParameters::Converter
+      include ArkEmail::Internal::Type::RequestParameters
+
+      # @!attribute webhook_id
+      #
+      #   @return [String]
+      required :webhook_id, String
+
+      # @!method initialize(webhook_id:, request_options: {})
+      #   @param webhook_id [String]
+      #   @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end

data/lib/ark_email/models/webhook_replay_delivery_response.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module ArkEmail
+  module Models
+    # @see ArkEmail::Resources::Webhooks#replay_delivery
+    class WebhookReplayDeliveryResponse < ArkEmail::Internal::Type::BaseModel
+      # @!attribute data
+      #
+      #   @return [ArkEmail::Models::WebhookReplayDeliveryResponse::Data]
+      required :data, -> { ArkEmail::Models::WebhookReplayDeliveryResponse::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)
+      #   Result of replaying a webhook delivery
+      #
+      #   @param data [ArkEmail::Models::WebhookReplayDeliveryResponse::Data]
+      #   @param meta [ArkEmail::Models::APIMeta]
+      #   @param success [Boolean, true]
+
+      # @see ArkEmail::Models::WebhookReplayDeliveryResponse#data
+      class Data < ArkEmail::Internal::Type::BaseModel
+        # @!attribute duration
+        #   Request duration in milliseconds
+        #
+        #   @return [Integer]
+        required :duration, Integer
+
+        # @!attribute new_delivery_id
+        #   ID of the new delivery created by the replay
+        #
+        #   @return [String]
+        required :new_delivery_id, String, api_name: :newDeliveryId
+
+        # @!attribute original_delivery_id
+        #   ID of the original delivery that was replayed
+        #
+        #   @return [String]
+        required :original_delivery_id, String, api_name: :originalDeliveryId
+
+        # @!attribute status_code
+        #   HTTP status code from your endpoint
+        #
+        #   @return [Integer, nil]
+        required :status_code, Integer, api_name: :statusCode, nil?: true
+
+        # @!attribute success
+        #   Whether the replay was successful (2xx response from endpoint)
+        #
+        #   @return [Boolean]
+        required :success, ArkEmail::Internal::Type::Boolean
+
+        # @!attribute timestamp
+        #   When the replay was executed
+        #
+        #   @return [Time]
+        required :timestamp, Time
+
+        # @!method initialize(duration:, new_delivery_id:, original_delivery_id:, status_code:, success:, timestamp:)
+        #   @param duration [Integer] Request duration in milliseconds
+        #
+        #   @param new_delivery_id [String] ID of the new delivery created by the replay
+        #
+        #   @param original_delivery_id [String] ID of the original delivery that was replayed
+        #
+        #   @param status_code [Integer, nil] HTTP status code from your endpoint
+        #
+        #   @param success [Boolean] Whether the replay was successful (2xx response from endpoint)
+        #
+        #   @param timestamp [Time] When the replay was executed
+      end
+    end
+  end
+end

data/lib/ark_email/models/webhook_retrieve_delivery_params.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ArkEmail
+  module Models
+    # @see ArkEmail::Resources::Webhooks#retrieve_delivery
+    class WebhookRetrieveDeliveryParams < ArkEmail::Internal::Type::BaseModel
+      extend ArkEmail::Internal::Type::RequestParameters::Converter
+      include ArkEmail::Internal::Type::RequestParameters
+
+      # @!attribute webhook_id
+      #
+      #   @return [String]
+      required :webhook_id, String
+
+      # @!method initialize(webhook_id:, request_options: {})
+      #   @param webhook_id [String]
+      #   @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end