ark-email 0.5.2 → 0.7.0

data/lib/ark_email/resources/tracking.rb

@@ -10,15 +10,15 @@ module ArkEmail
       #
       # @overload create(domain_id:, name:, ssl_enabled: nil, track_clicks: nil, track_opens: nil, request_options: {})
       #
-      # @param domain_id [String] ID of the sending domain to attach this track domain to
+      # @param domain_id [Integer] ID of the sending domain to attach this track domain to
       #
       # @param name [String] Subdomain name (e.g., 'track' for track.yourdomain.com)
       #
-      # @param ssl_enabled [Boolean] Enable SSL for tracking URLs (recommended)
+      # @param ssl_enabled [Boolean, nil] Enable SSL for tracking URLs (accepts null, defaults to true)
       #
-      # @param track_clicks [Boolean] Enable click tracking
+      # @param track_clicks [Boolean, nil] Enable click tracking (accepts null, defaults to true)
       #
-      # @param track_opens [Boolean] Enable open tracking (tracking pixel)
+      # @param track_opens [Boolean, nil] Enable open tracking (tracking pixel, accepts null, defaults to true)
       #
       # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
       #
@@ -69,13 +69,13 @@ module ArkEmail
       #
       # @param tracking_id [String] Track domain ID or UUID
       #
-      # @param excluded_click_domains [String] Comma-separated list of domains to exclude from click tracking
+      # @param excluded_click_domains [String, nil] Comma-separated list of domains to exclude from click tracking (accepts null)
       #
-      # @param ssl_enabled [Boolean] Enable or disable SSL for tracking URLs
+      # @param ssl_enabled [Boolean, nil] Enable or disable SSL for tracking URLs (accepts null)
       #
-      # @param track_clicks [Boolean] Enable or disable click tracking
+      # @param track_clicks [Boolean, nil] Enable or disable click tracking (accepts null)
       #
-      # @param track_opens [Boolean] Enable or disable open tracking
+      # @param track_opens [Boolean, nil] Enable or disable open tracking (accepts null)
       #
       # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
       #

data/lib/ark_email/resources/webhooks.rb

@@ -19,17 +19,17 @@ module ArkEmail
       # - `MessageLoaded` - Recipient opened the email
       # - `DomainDNSError` - Domain DNS issue detected
       #
-      # @overload create(events:, name:, url:, all_events: nil, enabled: nil, request_options: {})
-      #
-      # @param events [Array<Symbol, ArkEmail::Models::WebhookCreateParams::Event>] Events to subscribe to:
+      # @overload create(name:, url:, all_events: nil, enabled: nil, events: nil, request_options: {})
       #
       # @param name [String] Webhook name for identification
       #
       # @param url [String] HTTPS endpoint URL
       #
-      # @param all_events [Boolean] Subscribe to all events (ignores events array)
+      # @param all_events [Boolean, nil] Subscribe to all events (ignores events array, accepts null)
+      #
+      # @param enabled [Boolean, nil] Whether the webhook is enabled (accepts null)
       #
-      # @param enabled [Boolean]
+      # @param events [Array<Symbol, ArkEmail::Models::WebhookCreateParams::Event>, nil] Events to subscribe to (accepts null):
       #
       # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
       #
@@ -71,11 +71,11 @@ module ArkEmail
       # @overload update(webhook_id, all_events: nil, enabled: nil, events: nil, name: nil, url: nil, request_options: {})
       #
       # @param webhook_id [String]
-      # @param all_events [Boolean]
-      # @param enabled [Boolean]
-      # @param events [Array<String>]
-      # @param name [String]
-      # @param url [String]
+      # @param all_events [Boolean, nil]
+      # @param enabled [Boolean, nil]
+      # @param events [Array<String>, nil]
+      # @param name [String, nil]
+      # @param url [String, nil]
       # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
       #
       # @return [ArkEmail::Models::WebhookUpdateResponse]

data/lib/ark_email/version.rb

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

data/rbi/ark_email/models/email_send_batch_params.rbi

@@ -70,33 +70,55 @@ module ArkEmail
         attr_accessor :to
 
         sig { returns(T.nilable(String)) }
-        attr_reader :html
-
-        sig { params(html: String).void }
-        attr_writer :html
+        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).
+        sig { returns(T.nilable(T::Hash[Symbol, String])) }
+        attr_accessor :metadata
 
         sig { returns(T.nilable(String)) }
-        attr_reader :tag
-
-        sig { params(tag: String).void }
-        attr_writer :tag
+        attr_accessor :tag
 
         sig { returns(T.nilable(String)) }
-        attr_reader :text
-
-        sig { params(text: String).void }
-        attr_writer :text
+        attr_accessor :text
 
         sig do
           params(
             subject: String,
             to: T::Array[String],
-            html: String,
-            tag: String,
-            text: 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).
+          metadata: nil,
+          tag: nil,
+          text: nil
+        )
         end
 
         sig do
@@ -104,9 +126,10 @@ module ArkEmail
             {
               subject: String,
               to: T::Array[String],
-              html: String,
-              tag: String,
-              text: String
+              html: T.nilable(String),
+              metadata: T.nilable(T::Hash[Symbol, String]),
+              tag: T.nilable(String),
+              text: T.nilable(String)
             }
           )
         end

data/rbi/ark_email/models/email_send_params.rbi

@@ -31,69 +31,54 @@ module ArkEmail
       sig { returns(T::Array[String]) }
       attr_accessor :to
 
-      # File attachments
+      # File attachments (accepts null)
       sig do
         returns(T.nilable(T::Array[ArkEmail::EmailSendParams::Attachment]))
       end
-      attr_reader :attachments
+      attr_accessor :attachments
 
-      sig do
-        params(
-          attachments: T::Array[ArkEmail::EmailSendParams::Attachment::OrHash]
-        ).void
-      end
-      attr_writer :attachments
-
-      # BCC recipients
+      # BCC recipients (accepts null)
       sig { returns(T.nilable(T::Array[String])) }
-      attr_reader :bcc
-
-      sig { params(bcc: T::Array[String]).void }
-      attr_writer :bcc
+      attr_accessor :bcc
 
-      # CC recipients
+      # CC recipients (accepts null)
       sig { returns(T.nilable(T::Array[String])) }
-      attr_reader :cc
+      attr_accessor :cc
 
-      sig { params(cc: T::Array[String]).void }
-      attr_writer :cc
-
-      # Custom email headers
+      # Custom email headers (accepts null)
       sig { returns(T.nilable(T::Hash[Symbol, String])) }
-      attr_reader :headers
-
-      sig { params(headers: T::Hash[Symbol, String]).void }
-      attr_writer :headers
+      attr_accessor :headers
 
-      # HTML body content. Maximum 5MB (5,242,880 characters). Combined with
-      # attachments, the total message must not exceed 14MB.
+      # HTML body content (accepts null). Maximum 5MB (5,242,880 characters). Combined
+      # with attachments, the total message must not exceed 14MB.
       sig { returns(T.nilable(String)) }
-      attr_reader :html
+      attr_accessor :html
 
-      sig { params(html: String).void }
-      attr_writer :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).
+      sig { returns(T.nilable(T::Hash[Symbol, String])) }
+      attr_accessor :metadata
 
-      # Reply-to address
+      # Reply-to address (accepts null)
       sig { returns(T.nilable(String)) }
-      attr_reader :reply_to
+      attr_accessor :reply_to
 
-      sig { params(reply_to: String).void }
-      attr_writer :reply_to
-
-      # Tag for categorization and filtering
+      # Tag for categorization and filtering (accepts null)
       sig { returns(T.nilable(String)) }
-      attr_reader :tag
-
-      sig { params(tag: String).void }
-      attr_writer :tag
+      attr_accessor :tag
 
-      # Plain text body (auto-generated from HTML if not provided). Maximum 5MB
-      # (5,242,880 characters).
+      # Plain text body (accepts null, auto-generated from HTML if not provided).
+      # Maximum 5MB (5,242,880 characters).
       sig { returns(T.nilable(String)) }
-      attr_reader :text
-
-      sig { params(text: String).void }
-      attr_writer :text
+      attr_accessor :text
 
       sig { returns(T.nilable(String)) }
       attr_reader :idempotency_key
@@ -106,14 +91,16 @@ module ArkEmail
           from: String,
           subject: String,
           to: T::Array[String],
-          attachments: T::Array[ArkEmail::EmailSendParams::Attachment::OrHash],
-          bcc: T::Array[String],
-          cc: T::Array[String],
-          headers: T::Hash[Symbol, String],
-          html: String,
-          reply_to: String,
-          tag: String,
-          text: String,
+          attachments:
+            T.nilable(T::Array[ArkEmail::EmailSendParams::Attachment::OrHash]),
+          bcc: T.nilable(T::Array[String]),
+          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),
           idempotency_key: String,
           request_options: ArkEmail::RequestOptions::OrHash
         ).returns(T.attached_class)
@@ -133,23 +120,34 @@ module ArkEmail
         subject:,
         # Recipient email addresses (max 50)
         to:,
-        # File attachments
+        # File attachments (accepts null)
         attachments: nil,
-        # BCC recipients
+        # BCC recipients (accepts null)
         bcc: nil,
-        # CC recipients
+        # CC recipients (accepts null)
         cc: nil,
-        # Custom email headers
+        # Custom email headers (accepts null)
         headers: nil,
-        # HTML body content. Maximum 5MB (5,242,880 characters). Combined with
-        # attachments, the total message must not exceed 14MB.
+        # HTML body content (accepts null). Maximum 5MB (5,242,880 characters). Combined
+        # with attachments, the total message must not exceed 14MB.
         html: nil,
-        # Reply-to address
+        # 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).
+        metadata: nil,
+        # Reply-to address (accepts null)
         reply_to: nil,
-        # Tag for categorization and filtering
+        # Tag for categorization and filtering (accepts null)
         tag: nil,
-        # Plain text body (auto-generated from HTML if not provided). Maximum 5MB
-        # (5,242,880 characters).
+        # Plain text body (accepts null, auto-generated from HTML if not provided).
+        # Maximum 5MB (5,242,880 characters).
         text: nil,
         idempotency_key: nil,
         request_options: {}
@@ -162,14 +160,16 @@ module ArkEmail
             from: String,
             subject: String,
             to: T::Array[String],
-            attachments: T::Array[ArkEmail::EmailSendParams::Attachment],
-            bcc: T::Array[String],
-            cc: T::Array[String],
-            headers: T::Hash[Symbol, String],
-            html: String,
-            reply_to: String,
-            tag: String,
-            text: String,
+            attachments:
+              T.nilable(T::Array[ArkEmail::EmailSendParams::Attachment]),
+            bcc: T.nilable(T::Array[String]),
+            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),
             idempotency_key: String,
             request_options: ArkEmail::RequestOptions
           }

data/rbi/ark_email/models/email_send_raw_params.rbi

@@ -23,11 +23,16 @@ module ArkEmail
       sig { returns(T::Array[String]) }
       attr_accessor :rcpt_to
 
+      # Whether this is a bounce message (accepts null)
+      sig { returns(T.nilable(T::Boolean)) }
+      attr_accessor :bounce
+
       sig do
         params(
           data: String,
           mail_from: String,
           rcpt_to: T::Array[String],
+          bounce: T.nilable(T::Boolean),
           request_options: ArkEmail::RequestOptions::OrHash
         ).returns(T.attached_class)
       end
@@ -38,6 +43,8 @@ module ArkEmail
         mail_from:,
         # Envelope recipient addresses
         rcpt_to:,
+        # Whether this is a bounce message (accepts null)
+        bounce: nil,
         request_options: {}
       )
       end
@@ -48,6 +55,7 @@ module ArkEmail
             data: String,
             mail_from: String,
             rcpt_to: T::Array[String],
+            bounce: T.nilable(T::Boolean),
             request_options: ArkEmail::RequestOptions
           }
         )

data/rbi/ark_email/models/suppression_bulk_create_params.rbi

@@ -55,19 +55,23 @@ module ArkEmail
         sig { returns(String) }
         attr_accessor :address
 
+        # Reason for suppression (accepts null)
         sig { returns(T.nilable(String)) }
-        attr_reader :reason
-
-        sig { params(reason: String).void }
-        attr_writer :reason
+        attr_accessor :reason
 
         sig do
-          params(address: String, reason: String).returns(T.attached_class)
+          params(address: String, reason: T.nilable(String)).returns(
+            T.attached_class
+          )
         end
-        def self.new(address:, reason: nil)
+        def self.new(
+          address:,
+          # Reason for suppression (accepts null)
+          reason: nil
+        )
         end
 
-        sig { override.returns({ address: String, reason: String }) }
+        sig { override.returns({ address: String, reason: T.nilable(String) }) }
         def to_hash
         end
       end

data/rbi/ark_email/models/suppression_create_params.rbi

@@ -15,24 +15,21 @@ module ArkEmail
       sig { returns(String) }
       attr_accessor :address
 
-      # Reason for suppression
+      # Reason for suppression (accepts null)
       sig { returns(T.nilable(String)) }
-      attr_reader :reason
-
-      sig { params(reason: String).void }
-      attr_writer :reason
+      attr_accessor :reason
 
       sig do
         params(
           address: String,
-          reason: String,
+          reason: T.nilable(String),
           request_options: ArkEmail::RequestOptions::OrHash
         ).returns(T.attached_class)
       end
       def self.new(
         # Email address to suppress
         address:,
-        # Reason for suppression
+        # Reason for suppression (accepts null)
         reason: nil,
         request_options: {}
       )
@@ -42,7 +39,7 @@ module ArkEmail
         override.returns(
           {
             address: String,
-            reason: String,
+            reason: T.nilable(String),
             request_options: ArkEmail::RequestOptions
           }
         )

data/rbi/ark_email/models/tracking_create_params.rbi

@@ -12,41 +12,32 @@ module ArkEmail
         end
 
       # ID of the sending domain to attach this track domain to
-      sig { returns(String) }
+      sig { returns(Integer) }
       attr_accessor :domain_id
 
       # Subdomain name (e.g., 'track' for track.yourdomain.com)
       sig { returns(String) }
       attr_accessor :name
 
-      # Enable SSL for tracking URLs (recommended)
+      # Enable SSL for tracking URLs (accepts null, defaults to true)
       sig { returns(T.nilable(T::Boolean)) }
-      attr_reader :ssl_enabled
-
-      sig { params(ssl_enabled: T::Boolean).void }
-      attr_writer :ssl_enabled
+      attr_accessor :ssl_enabled
 
-      # Enable click tracking
+      # Enable click tracking (accepts null, defaults to true)
       sig { returns(T.nilable(T::Boolean)) }
-      attr_reader :track_clicks
+      attr_accessor :track_clicks
 
-      sig { params(track_clicks: T::Boolean).void }
-      attr_writer :track_clicks
-
-      # Enable open tracking (tracking pixel)
+      # Enable open tracking (tracking pixel, accepts null, defaults to true)
       sig { returns(T.nilable(T::Boolean)) }
-      attr_reader :track_opens
-
-      sig { params(track_opens: T::Boolean).void }
-      attr_writer :track_opens
+      attr_accessor :track_opens
 
       sig do
         params(
-          domain_id: String,
+          domain_id: Integer,
           name: String,
-          ssl_enabled: T::Boolean,
-          track_clicks: T::Boolean,
-          track_opens: T::Boolean,
+          ssl_enabled: T.nilable(T::Boolean),
+          track_clicks: T.nilable(T::Boolean),
+          track_opens: T.nilable(T::Boolean),
           request_options: ArkEmail::RequestOptions::OrHash
         ).returns(T.attached_class)
       end
@@ -55,11 +46,11 @@ module ArkEmail
         domain_id:,
         # Subdomain name (e.g., 'track' for track.yourdomain.com)
         name:,
-        # Enable SSL for tracking URLs (recommended)
+        # Enable SSL for tracking URLs (accepts null, defaults to true)
         ssl_enabled: nil,
-        # Enable click tracking
+        # Enable click tracking (accepts null, defaults to true)
         track_clicks: nil,
-        # Enable open tracking (tracking pixel)
+        # Enable open tracking (tracking pixel, accepts null, defaults to true)
         track_opens: nil,
         request_options: {}
       )
@@ -68,11 +59,11 @@ module ArkEmail
       sig do
         override.returns(
           {
-            domain_id: String,
+            domain_id: Integer,
             name: String,
-            ssl_enabled: T::Boolean,
-            track_clicks: T::Boolean,
-            track_opens: T::Boolean,
+            ssl_enabled: T.nilable(T::Boolean),
+            track_clicks: T.nilable(T::Boolean),
+            track_opens: T.nilable(T::Boolean),
             request_options: ArkEmail::RequestOptions
           }
         )

data/rbi/ark_email/models/tracking_update_params.rbi

@@ -11,51 +11,39 @@ module ArkEmail
           T.any(ArkEmail::TrackingUpdateParams, ArkEmail::Internal::AnyHash)
         end
 
-      # Comma-separated list of domains to exclude from click tracking
+      # Comma-separated list of domains to exclude from click tracking (accepts null)
       sig { returns(T.nilable(String)) }
-      attr_reader :excluded_click_domains
+      attr_accessor :excluded_click_domains
 
-      sig { params(excluded_click_domains: String).void }
-      attr_writer :excluded_click_domains
-
-      # Enable or disable SSL for tracking URLs
+      # Enable or disable SSL for tracking URLs (accepts null)
       sig { returns(T.nilable(T::Boolean)) }
-      attr_reader :ssl_enabled
-
-      sig { params(ssl_enabled: T::Boolean).void }
-      attr_writer :ssl_enabled
+      attr_accessor :ssl_enabled
 
-      # Enable or disable click tracking
+      # Enable or disable click tracking (accepts null)
       sig { returns(T.nilable(T::Boolean)) }
-      attr_reader :track_clicks
+      attr_accessor :track_clicks
 
-      sig { params(track_clicks: T::Boolean).void }
-      attr_writer :track_clicks
-
-      # Enable or disable open tracking
+      # Enable or disable open tracking (accepts null)
       sig { returns(T.nilable(T::Boolean)) }
-      attr_reader :track_opens
-
-      sig { params(track_opens: T::Boolean).void }
-      attr_writer :track_opens
+      attr_accessor :track_opens
 
       sig do
         params(
-          excluded_click_domains: String,
-          ssl_enabled: T::Boolean,
-          track_clicks: T::Boolean,
-          track_opens: T::Boolean,
+          excluded_click_domains: T.nilable(String),
+          ssl_enabled: T.nilable(T::Boolean),
+          track_clicks: T.nilable(T::Boolean),
+          track_opens: T.nilable(T::Boolean),
           request_options: ArkEmail::RequestOptions::OrHash
         ).returns(T.attached_class)
       end
       def self.new(
-        # Comma-separated list of domains to exclude from click tracking
+        # Comma-separated list of domains to exclude from click tracking (accepts null)
         excluded_click_domains: nil,
-        # Enable or disable SSL for tracking URLs
+        # Enable or disable SSL for tracking URLs (accepts null)
         ssl_enabled: nil,
-        # Enable or disable click tracking
+        # Enable or disable click tracking (accepts null)
         track_clicks: nil,
-        # Enable or disable open tracking
+        # Enable or disable open tracking (accepts null)
         track_opens: nil,
         request_options: {}
       )
@@ -64,10 +52,10 @@ module ArkEmail
       sig do
         override.returns(
           {
-            excluded_click_domains: String,
-            ssl_enabled: T::Boolean,
-            track_clicks: T::Boolean,
-            track_opens: T::Boolean,
+            excluded_click_domains: T.nilable(String),
+            ssl_enabled: T.nilable(T::Boolean),
+            track_clicks: T.nilable(T::Boolean),
+            track_opens: T.nilable(T::Boolean),
             request_options: ArkEmail::RequestOptions
           }
         )