ark-email 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b28db2b8003c270a67cebc743ea403628c8a13a8d0cff4b4e357704aae84c55
-  data.tar.gz: 8ccf63ab298517800021888ab0e2041d4eb5b66c27735d16e3ed2c630fb3eab7
+  metadata.gz: a5bff73c450d51ba2c0214d2fa1a15c67c3252e32ba41754b22ba947d333c6c9
+  data.tar.gz: bef229fb5def2ff8711e410cb00e86e882828d4fa427b46f96c0d06155d0b48b
 SHA512:
-  metadata.gz: ebe864f749bc491e0d8d190661a3c265050b59d7a21e7e8bf97b4fb52c148040a02b42f51d03e7f5b2e19119c75abf1581ab78835d66529632453b4a206a7064
-  data.tar.gz: 0bd1b269b07c48c3514ec03cb0a7372c980f8f4ee48687b06c8bb7593cd2ea0303d6b22aa7bbc8300462294bd2132cf0232e87b585376a0f96470040941591c9
+  metadata.gz: 70ebcf12bce9fc793a3c383f026a338cb896101ca7eebb1a912b6ca1fca41006dc30e2e68705c80d43d61792b1739d5f89249e9062266ea847ee0c11c40f1f3e
+  data.tar.gz: a14f81353ad5109090ebb94092fd81d378ebc374b24f9a202533510ab3515744487316aabcf11175f6ba042846fbd91a6bf87b5003d3e38b0112598a202652a3

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.10.0 (2026-01-22)
+
+Full Changelog: [v0.9.0...v0.10.0](https://github.com/ArkHQ-io/ark-ruby/compare/v0.9.0...v0.10.0)
+
+### Features
+
+* **api:** improve GET delivery attempts ([863df8e](https://github.com/ArkHQ-io/ark-ruby/commit/863df8e1ca7e4e29f44fdd1ffb9583fc71e5245e))
+
+## 0.9.0 (2026-01-21)
+
+Full Changelog: [v0.8.0...v0.9.0](https://github.com/ArkHQ-io/ark-ruby/compare/v0.8.0...v0.9.0)
+
+### Features
+
+* **api:** add sandbox domain ([d61ffa2](https://github.com/ArkHQ-io/ark-ruby/commit/d61ffa220016820c5620ba168461e82fab223ed4))
+
 ## 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)

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.8.0"
+gem "ark-email", "~> 0.10.0"
 ```
 
 <!-- x-release-please-end -->

data/lib/ark_email/models/email_retrieve_deliveries_response.rb

@@ -26,30 +26,72 @@ module ArkEmail
 
       # @see ArkEmail::Models::EmailRetrieveDeliveriesResponse#data
       class Data < ArkEmail::Internal::Type::BaseModel
+        # @!attribute can_retry_manually
+        #   Whether the message can be manually retried via `POST /emails/{emailId}/retry`.
+        #   `true` when the raw message content is still available (not expired). Messages
+        #   older than the retention period cannot be retried.
+        #
+        #   @return [Boolean]
+        required :can_retry_manually, ArkEmail::Internal::Type::Boolean, api_name: :canRetryManually
+
         # @!attribute deliveries
+        #   Chronological list of delivery attempts for this message. Each attempt includes
+        #   SMTP response codes and timestamps.
         #
         #   @return [Array<ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery>]
         required :deliveries,
                  -> { ArkEmail::Internal::Type::ArrayOf[ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery] }
 
         # @!attribute message_id
-        #   Internal message ID
+        #   Internal numeric message ID
         #
-        #   @return [String]
-        required :message_id, String, api_name: :messageId
+        #   @return [Integer]
+        required :message_id, Integer, api_name: :messageId
 
         # @!attribute message_token
-        #   Message token
+        #   Unique message token for API references
         #
         #   @return [String]
         required :message_token, String, api_name: :messageToken
 
-        # @!method initialize(deliveries:, message_id:, message_token:)
-        #   @param deliveries [Array<ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery>]
+        # @!attribute retry_state
+        #   Information about the current retry state of a message that is queued for
+        #   delivery. Only present when the message is in the delivery queue.
         #
-        #   @param message_id [String] Internal message ID
+        #   @return [ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::RetryState, nil]
+        required :retry_state,
+                 -> { ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::RetryState },
+                 api_name: :retryState,
+                 nil?: true
+
+        # @!attribute status
+        #   Current message status (lowercase). Possible values:
+        #
+        #   - `pending` - Initial state, awaiting first delivery attempt
+        #   - `sent` - Successfully delivered
+        #   - `softfail` - Temporary failure, will retry automatically
+        #   - `hardfail` - Permanent failure, will not retry
+        #   - `held` - Held for manual review (suppression list, etc.)
+        #   - `bounced` - Bounced by recipient server
         #
-        #   @param message_token [String] Message token
+        #   @return [Symbol, ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Status]
+        required :status, enum: -> { ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Status }
+
+        # @!method initialize(can_retry_manually:, deliveries:, message_id:, message_token:, retry_state:, status:)
+        #   Some parameter documentations has been truncated, see
+        #   {ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data} for more details.
+        #
+        #   @param can_retry_manually [Boolean] Whether the message can be manually retried via `POST /emails/{emailId}/retry`.
+        #
+        #   @param deliveries [Array<ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery>] Chronological list of delivery attempts for this message.
+        #
+        #   @param message_id [Integer] Internal numeric message ID
+        #
+        #   @param message_token [String] Unique message token for API references
+        #
+        #   @param retry_state [ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::RetryState, nil] Information about the current retry state of a message that is queued for delive
+        #
+        #   @param status [Symbol, ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Status] Current message status (lowercase). Possible values:
 
         class Delivery < ArkEmail::Internal::Type::BaseModel
           # @!attribute id
@@ -117,6 +159,104 @@ module ArkEmail
           #
           #   @param sent_with_ssl [Boolean] Whether TLS was used
         end
+
+        # @see ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data#retry_state
+        class RetryState < ArkEmail::Internal::Type::BaseModel
+          # @!attribute attempt
+          #   Current attempt number (0-indexed). The first delivery attempt is 0, the first
+          #   retry is 1, and so on.
+          #
+          #   @return [Integer]
+          required :attempt, Integer
+
+          # @!attribute attempts_remaining
+          #   Number of attempts remaining before the message is hard-failed. Calculated as
+          #   `maxAttempts - attempt`.
+          #
+          #   @return [Integer]
+          required :attempts_remaining, Integer, api_name: :attemptsRemaining
+
+          # @!attribute manual
+          #   Whether this queue entry was created by a manual retry request. Manual retries
+          #   bypass certain hold conditions like suppression lists.
+          #
+          #   @return [Boolean]
+          required :manual, ArkEmail::Internal::Type::Boolean
+
+          # @!attribute max_attempts
+          #   Maximum number of delivery attempts before the message is hard-failed.
+          #   Configured at the server level.
+          #
+          #   @return [Integer]
+          required :max_attempts, Integer, api_name: :maxAttempts
+
+          # @!attribute processing
+          #   Whether the message is currently being processed by a delivery worker. When
+          #   `true`, the message is actively being sent.
+          #
+          #   @return [Boolean]
+          required :processing, ArkEmail::Internal::Type::Boolean
+
+          # @!attribute next_retry_at
+          #   Unix timestamp of when the next retry attempt is scheduled. `null` if the
+          #   message is ready for immediate processing or currently being processed.
+          #
+          #   @return [Float, nil]
+          optional :next_retry_at, Float, api_name: :nextRetryAt, nil?: true
+
+          # @!attribute next_retry_at_iso
+          #   ISO 8601 formatted timestamp of the next retry attempt. `null` if the message is
+          #   ready for immediate processing.
+          #
+          #   @return [Time, nil]
+          optional :next_retry_at_iso, Time, api_name: :nextRetryAtIso, nil?: true
+
+          # @!method initialize(attempt:, attempts_remaining:, manual:, max_attempts:, processing:, next_retry_at: nil, next_retry_at_iso: nil)
+          #   Some parameter documentations has been truncated, see
+          #   {ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::RetryState} for more
+          #   details.
+          #
+          #   Information about the current retry state of a message that is queued for
+          #   delivery. Only present when the message is in the delivery queue.
+          #
+          #   @param attempt [Integer] Current attempt number (0-indexed). The first delivery attempt is 0,
+          #
+          #   @param attempts_remaining [Integer] Number of attempts remaining before the message is hard-failed.
+          #
+          #   @param manual [Boolean] Whether this queue entry was created by a manual retry request.
+          #
+          #   @param max_attempts [Integer] Maximum number of delivery attempts before the message is hard-failed.
+          #
+          #   @param processing [Boolean] Whether the message is currently being processed by a delivery worker.
+          #
+          #   @param next_retry_at [Float, nil] Unix timestamp of when the next retry attempt is scheduled.
+          #
+          #   @param next_retry_at_iso [Time, nil] ISO 8601 formatted timestamp of the next retry attempt.
+        end
+
+        # Current message status (lowercase). Possible values:
+        #
+        # - `pending` - Initial state, awaiting first delivery attempt
+        # - `sent` - Successfully delivered
+        # - `softfail` - Temporary failure, will retry automatically
+        # - `hardfail` - Permanent failure, will not retry
+        # - `held` - Held for manual review (suppression list, etc.)
+        # - `bounced` - Bounced by recipient server
+        #
+        # @see ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data#status
+        module Status
+          extend ArkEmail::Internal::Type::Enum
+
+          PENDING = :pending
+          SENT = :sent
+          SOFTFAIL = :softfail
+          HARDFAIL = :hardfail
+          HELD = :held
+          BOUNCED = :bounced
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
       end
     end
   end

data/lib/ark_email/models/email_send_batch_response.rb

@@ -51,7 +51,17 @@ module ArkEmail
         #   @return [Integer]
         required :total, Integer
 
-        # @!method initialize(accepted:, failed:, messages:, total:)
+        # @!attribute sandbox
+        #   Whether this batch was sent in sandbox mode. Only present (and true) for sandbox
+        #   emails sent from @arkhq.io addresses.
+        #
+        #   @return [Boolean, nil]
+        optional :sandbox, ArkEmail::Internal::Type::Boolean
+
+        # @!method initialize(accepted:, failed:, messages:, total:, sandbox: nil)
+        #   Some parameter documentations has been truncated, see
+        #   {ArkEmail::Models::EmailSendBatchResponse::Data} for more details.
+        #
         #   @param accepted [Integer] Successfully accepted emails
         #
         #   @param failed [Integer] Failed emails
@@ -59,6 +69,8 @@ module ArkEmail
         #   @param messages [Hash{Symbol=>ArkEmail::Models::EmailSendBatchResponse::Data::Message}] Map of recipient email to message info
         #
         #   @param total [Integer] Total emails in the batch
+        #
+        #   @param sandbox [Boolean] Whether this batch was sent in sandbox mode.
 
         class Message < ArkEmail::Internal::Type::BaseModel
           # @!attribute id

data/lib/ark_email/models/email_send_params.rb

@@ -8,7 +8,7 @@ module ArkEmail
       include ArkEmail::Internal::Type::RequestParameters
 
       # @!attribute from
-      #   Sender email address. Must be from a verified domain.
+      #   Sender email address. Must be from a verified domain OR use sandbox mode.
       #
       #   **Supported formats:**
       #
@@ -18,6 +18,10 @@ module ArkEmail
       #
       #   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.
+      #
       #   @return [String]
       required :from, String
 
@@ -117,7 +121,7 @@ module ArkEmail
       #   Some parameter documentations has been truncated, see
       #   {ArkEmail::Models::EmailSendParams} for more details.
       #
-      #   @param from [String] Sender email address. Must be from a verified domain.
+      #   @param from [String] Sender email address. Must be from a verified domain OR use sandbox mode.
       #
       #   @param subject [String] Email subject line
       #

data/lib/ark_email/models/email_send_raw_response.rb

@@ -50,7 +50,17 @@ module ArkEmail
         #   @return [String, nil]
         optional :message_id, String, api_name: :messageId
 
-        # @!method initialize(id:, status:, to:, message_id: nil)
+        # @!attribute sandbox
+        #   Whether this email was sent in sandbox mode. Only present (and true) for sandbox
+        #   emails sent from @arkhq.io addresses.
+        #
+        #   @return [Boolean, nil]
+        optional :sandbox, ArkEmail::Internal::Type::Boolean
+
+        # @!method initialize(id:, status:, to:, message_id: nil, sandbox: nil)
+        #   Some parameter documentations has been truncated, see
+        #   {ArkEmail::Models::EmailSendRawResponse::Data} for more details.
+        #
         #   @param id [String] Unique message ID (format: msg*{id}*{token})
         #
         #   @param status [Symbol, ArkEmail::Models::EmailSendRawResponse::Data::Status] Current delivery status
@@ -58,6 +68,8 @@ module ArkEmail
         #   @param to [Array<String>] List of recipient addresses
         #
         #   @param message_id [String] SMTP Message-ID header value
+        #
+        #   @param sandbox [Boolean] Whether this email was sent in sandbox mode.
 
         # Current delivery status
         #

data/lib/ark_email/models/email_send_response.rb

@@ -50,7 +50,17 @@ module ArkEmail
         #   @return [String, nil]
         optional :message_id, String, api_name: :messageId
 
-        # @!method initialize(id:, status:, to:, message_id: nil)
+        # @!attribute sandbox
+        #   Whether this email was sent in sandbox mode. Only present (and true) for sandbox
+        #   emails sent from @arkhq.io addresses.
+        #
+        #   @return [Boolean, nil]
+        optional :sandbox, ArkEmail::Internal::Type::Boolean
+
+        # @!method initialize(id:, status:, to:, message_id: nil, sandbox: nil)
+        #   Some parameter documentations has been truncated, see
+        #   {ArkEmail::Models::EmailSendResponse::Data} for more details.
+        #
         #   @param id [String] Unique message ID (format: msg*{id}*{token})
         #
         #   @param status [Symbol, ArkEmail::Models::EmailSendResponse::Data::Status] Current delivery status
@@ -58,6 +68,8 @@ module ArkEmail
         #   @param to [Array<String>] List of recipient addresses
         #
         #   @param message_id [String] SMTP Message-ID header value
+        #
+        #   @param sandbox [Boolean] Whether this email was sent in sandbox mode.
 
         # Current delivery status
         #

data/lib/ark_email/resources/emails.rb

@@ -82,12 +82,50 @@ module ArkEmail
         )
       end
 
-      # Get the history of delivery attempts for an email, including SMTP response codes
-      # and timestamps.
+      # Some parameter documentations has been truncated, see
+      # {ArkEmail::Models::EmailRetrieveDeliveriesParams} for more details.
+      #
+      # Get the complete delivery history for an email, including SMTP response codes,
+      # timestamps, and current retry state.
+      #
+      # ## Response Fields
+      #
+      # ### Status
+      #
+      # The current status of the email:
+      #
+      # - `pending` - Awaiting first delivery attempt
+      # - `sent` - Successfully delivered to recipient server
+      # - `softfail` - Temporary failure, automatic retry scheduled
+      # - `hardfail` - Permanent failure, will not retry
+      # - `held` - Held for manual review
+      # - `bounced` - Bounced by recipient server
+      #
+      # ### Retry State
+      #
+      # When the email is in the delivery queue (`pending` or `softfail` status),
+      # `retryState` provides information about the retry schedule:
+      #
+      # - `attempt` - Current attempt number (0 = first attempt)
+      # - `maxAttempts` - Maximum attempts before hard-fail (typically 18)
+      # - `attemptsRemaining` - Attempts left before hard-fail
+      # - `nextRetryAt` - When the next retry is scheduled (Unix timestamp)
+      # - `processing` - Whether the email is currently being processed
+      # - `manual` - Whether this was triggered by a manual retry
+      #
+      # When the email has finished processing (`sent`, `hardfail`, `held`, `bounced`),
+      # `retryState` is `null`.
+      #
+      # ### Can Retry Manually
+      #
+      # Indicates whether you can call `POST /emails/{emailId}/retry` to manually retry
+      # the email. This is `true` when the raw message content is still available (not
+      # expired due to retention policy).
       #
       # @overload retrieve_deliveries(email_id, request_options: {})
       #
-      # @param email_id [String]
+      # @param email_id [String] Email identifier. Accepts multiple formats:
+      #
       # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
       #
       # @return [ArkEmail::Models::EmailRetrieveDeliveriesResponse]
@@ -144,7 +182,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/version.rb

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

data/rbi/ark_email/models/email_retrieve_deliveries_response.rbi

@@ -61,6 +61,14 @@ module ArkEmail
             )
           end
 
+        # Whether the message can be manually retried via `POST /emails/{emailId}/retry`.
+        # `true` when the raw message content is still available (not expired). Messages
+        # older than the retention period cannot be retried.
+        sig { returns(T::Boolean) }
+        attr_accessor :can_retry_manually
+
+        # Chronological list of delivery attempts for this message. Each attempt includes
+        # SMTP response codes and timestamps.
         sig do
           returns(
             T::Array[
@@ -70,42 +78,110 @@ module ArkEmail
         end
         attr_accessor :deliveries
 
-        # Internal message ID
-        sig { returns(String) }
+        # Internal numeric message ID
+        sig { returns(Integer) }
         attr_accessor :message_id
 
-        # Message token
+        # Unique message token for API references
         sig { returns(String) }
         attr_accessor :message_token
 
+        # Information about the current retry state of a message that is queued for
+        # delivery. Only present when the message is in the delivery queue.
+        sig do
+          returns(
+            T.nilable(
+              ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::RetryState
+            )
+          )
+        end
+        attr_reader :retry_state
+
+        sig do
+          params(
+            retry_state:
+              T.nilable(
+                ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::RetryState::OrHash
+              )
+          ).void
+        end
+        attr_writer :retry_state
+
+        # Current message status (lowercase). Possible values:
+        #
+        # - `pending` - Initial state, awaiting first delivery attempt
+        # - `sent` - Successfully delivered
+        # - `softfail` - Temporary failure, will retry automatically
+        # - `hardfail` - Permanent failure, will not retry
+        # - `held` - Held for manual review (suppression list, etc.)
+        # - `bounced` - Bounced by recipient server
+        sig do
+          returns(
+            ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Status::TaggedSymbol
+          )
+        end
+        attr_accessor :status
+
         sig do
           params(
+            can_retry_manually: T::Boolean,
             deliveries:
               T::Array[
                 ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery::OrHash
               ],
-            message_id: String,
-            message_token: String
+            message_id: Integer,
+            message_token: String,
+            retry_state:
+              T.nilable(
+                ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::RetryState::OrHash
+              ),
+            status:
+              ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Status::OrSymbol
           ).returns(T.attached_class)
         end
         def self.new(
+          # Whether the message can be manually retried via `POST /emails/{emailId}/retry`.
+          # `true` when the raw message content is still available (not expired). Messages
+          # older than the retention period cannot be retried.
+          can_retry_manually:,
+          # Chronological list of delivery attempts for this message. Each attempt includes
+          # SMTP response codes and timestamps.
           deliveries:,
-          # Internal message ID
+          # Internal numeric message ID
           message_id:,
-          # Message token
-          message_token:
+          # Unique message token for API references
+          message_token:,
+          # Information about the current retry state of a message that is queued for
+          # delivery. Only present when the message is in the delivery queue.
+          retry_state:,
+          # Current message status (lowercase). Possible values:
+          #
+          # - `pending` - Initial state, awaiting first delivery attempt
+          # - `sent` - Successfully delivered
+          # - `softfail` - Temporary failure, will retry automatically
+          # - `hardfail` - Permanent failure, will not retry
+          # - `held` - Held for manual review (suppression list, etc.)
+          # - `bounced` - Bounced by recipient server
+          status:
         )
         end
 
         sig do
           override.returns(
             {
+              can_retry_manually: T::Boolean,
               deliveries:
                 T::Array[
                   ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery
                 ],
-              message_id: String,
-              message_token: String
+              message_id: Integer,
+              message_token: String,
+              retry_state:
+                T.nilable(
+                  ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::RetryState
+                ),
+              status:
+                ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Status::TaggedSymbol
             }
           )
         end
@@ -214,6 +290,167 @@ module ArkEmail
           def to_hash
           end
         end
+
+        class RetryState < ArkEmail::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::RetryState,
+                ArkEmail::Internal::AnyHash
+              )
+            end
+
+          # Current attempt number (0-indexed). The first delivery attempt is 0, the first
+          # retry is 1, and so on.
+          sig { returns(Integer) }
+          attr_accessor :attempt
+
+          # Number of attempts remaining before the message is hard-failed. Calculated as
+          # `maxAttempts - attempt`.
+          sig { returns(Integer) }
+          attr_accessor :attempts_remaining
+
+          # Whether this queue entry was created by a manual retry request. Manual retries
+          # bypass certain hold conditions like suppression lists.
+          sig { returns(T::Boolean) }
+          attr_accessor :manual
+
+          # Maximum number of delivery attempts before the message is hard-failed.
+          # Configured at the server level.
+          sig { returns(Integer) }
+          attr_accessor :max_attempts
+
+          # Whether the message is currently being processed by a delivery worker. When
+          # `true`, the message is actively being sent.
+          sig { returns(T::Boolean) }
+          attr_accessor :processing
+
+          # Unix timestamp of when the next retry attempt is scheduled. `null` if the
+          # message is ready for immediate processing or currently being processed.
+          sig { returns(T.nilable(Float)) }
+          attr_accessor :next_retry_at
+
+          # ISO 8601 formatted timestamp of the next retry attempt. `null` if the message is
+          # ready for immediate processing.
+          sig { returns(T.nilable(Time)) }
+          attr_accessor :next_retry_at_iso
+
+          # Information about the current retry state of a message that is queued for
+          # delivery. Only present when the message is in the delivery queue.
+          sig do
+            params(
+              attempt: Integer,
+              attempts_remaining: Integer,
+              manual: T::Boolean,
+              max_attempts: Integer,
+              processing: T::Boolean,
+              next_retry_at: T.nilable(Float),
+              next_retry_at_iso: T.nilable(Time)
+            ).returns(T.attached_class)
+          end
+          def self.new(
+            # Current attempt number (0-indexed). The first delivery attempt is 0, the first
+            # retry is 1, and so on.
+            attempt:,
+            # Number of attempts remaining before the message is hard-failed. Calculated as
+            # `maxAttempts - attempt`.
+            attempts_remaining:,
+            # Whether this queue entry was created by a manual retry request. Manual retries
+            # bypass certain hold conditions like suppression lists.
+            manual:,
+            # Maximum number of delivery attempts before the message is hard-failed.
+            # Configured at the server level.
+            max_attempts:,
+            # Whether the message is currently being processed by a delivery worker. When
+            # `true`, the message is actively being sent.
+            processing:,
+            # Unix timestamp of when the next retry attempt is scheduled. `null` if the
+            # message is ready for immediate processing or currently being processed.
+            next_retry_at: nil,
+            # ISO 8601 formatted timestamp of the next retry attempt. `null` if the message is
+            # ready for immediate processing.
+            next_retry_at_iso: nil
+          )
+          end
+
+          sig do
+            override.returns(
+              {
+                attempt: Integer,
+                attempts_remaining: Integer,
+                manual: T::Boolean,
+                max_attempts: Integer,
+                processing: T::Boolean,
+                next_retry_at: T.nilable(Float),
+                next_retry_at_iso: T.nilable(Time)
+              }
+            )
+          end
+          def to_hash
+          end
+        end
+
+        # Current message status (lowercase). Possible values:
+        #
+        # - `pending` - Initial state, awaiting first delivery attempt
+        # - `sent` - Successfully delivered
+        # - `softfail` - Temporary failure, will retry automatically
+        # - `hardfail` - Permanent failure, will not retry
+        # - `held` - Held for manual review (suppression list, etc.)
+        # - `bounced` - Bounced by recipient server
+        module Status
+          extend ArkEmail::Internal::Type::Enum
+
+          TaggedSymbol =
+            T.type_alias do
+              T.all(
+                Symbol,
+                ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Status
+              )
+            end
+          OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+          PENDING =
+            T.let(
+              :pending,
+              ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Status::TaggedSymbol
+            )
+          SENT =
+            T.let(
+              :sent,
+              ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Status::TaggedSymbol
+            )
+          SOFTFAIL =
+            T.let(
+              :softfail,
+              ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Status::TaggedSymbol
+            )
+          HARDFAIL =
+            T.let(
+              :hardfail,
+              ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Status::TaggedSymbol
+            )
+          HELD =
+            T.let(
+              :held,
+              ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Status::TaggedSymbol
+            )
+          BOUNCED =
+            T.let(
+              :bounced,
+              ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Status::TaggedSymbol
+            )
+
+          sig do
+            override.returns(
+              T::Array[
+                ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Status::TaggedSymbol
+              ]
+            )
+          end
+          def self.values
+          end
+        end
       end
     end
   end

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
 
@@ -114,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:**
         #
@@ -123,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:,

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

data/rbi/ark_email/resources/emails.rbi

@@ -83,15 +83,57 @@ module ArkEmail
       )
       end
 
-      # Get the history of delivery attempts for an email, including SMTP response codes
-      # and timestamps.
+      # Get the complete delivery history for an email, including SMTP response codes,
+      # timestamps, and current retry state.
+      #
+      # ## Response Fields
+      #
+      # ### Status
+      #
+      # The current status of the email:
+      #
+      # - `pending` - Awaiting first delivery attempt
+      # - `sent` - Successfully delivered to recipient server
+      # - `softfail` - Temporary failure, automatic retry scheduled
+      # - `hardfail` - Permanent failure, will not retry
+      # - `held` - Held for manual review
+      # - `bounced` - Bounced by recipient server
+      #
+      # ### Retry State
+      #
+      # When the email is in the delivery queue (`pending` or `softfail` status),
+      # `retryState` provides information about the retry schedule:
+      #
+      # - `attempt` - Current attempt number (0 = first attempt)
+      # - `maxAttempts` - Maximum attempts before hard-fail (typically 18)
+      # - `attemptsRemaining` - Attempts left before hard-fail
+      # - `nextRetryAt` - When the next retry is scheduled (Unix timestamp)
+      # - `processing` - Whether the email is currently being processed
+      # - `manual` - Whether this was triggered by a manual retry
+      #
+      # When the email has finished processing (`sent`, `hardfail`, `held`, `bounced`),
+      # `retryState` is `null`.
+      #
+      # ### Can Retry Manually
+      #
+      # Indicates whether you can call `POST /emails/{emailId}/retry` to manually retry
+      # the email. This is `true` when the raw message content is still available (not
+      # expired due to retention policy).
       sig do
         params(
           email_id: String,
           request_options: ArkEmail::RequestOptions::OrHash
         ).returns(ArkEmail::Models::EmailRetrieveDeliveriesResponse)
       end
-      def retrieve_deliveries(email_id, request_options: {})
+      def retrieve_deliveries(
+        # Email identifier. Accepts multiple formats:
+        #
+        # - Message ID (numeric): `12345`
+        # - Message token: `aBc123XyZ`
+        # - Combined format: `msg_12345_aBc123XyZ`
+        email_id,
+        request_options: {}
+      )
       end
 
       # Retry delivery of a failed or soft-bounced email. Creates a new delivery
@@ -141,7 +183,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 +193,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:,

data/sig/ark_email/models/email_retrieve_deliveries_response.rbs

@@ -28,28 +28,43 @@ module ArkEmail
 
       type data =
         {
+          can_retry_manually: bool,
           deliveries: ::Array[ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery],
-          message_id: String,
-          message_token: String
+          message_id: Integer,
+          message_token: String,
+          retry_state: ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::RetryState?,
+          status: ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::status
         }
 
       class Data < ArkEmail::Internal::Type::BaseModel
+        attr_accessor can_retry_manually: bool
+
         attr_accessor deliveries: ::Array[ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery]
 
-        attr_accessor message_id: String
+        attr_accessor message_id: Integer
 
         attr_accessor message_token: String
 
+        attr_accessor retry_state: ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::RetryState?
+
+        attr_accessor status: ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::status
+
         def initialize: (
+          can_retry_manually: bool,
           deliveries: ::Array[ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery],
-          message_id: String,
-          message_token: String
+          message_id: Integer,
+          message_token: String,
+          retry_state: ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::RetryState?,
+          status: ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::status
         ) -> void
 
         def to_hash: -> {
+          can_retry_manually: bool,
           deliveries: ::Array[ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery],
-          message_id: String,
-          message_token: String
+          message_id: Integer,
+          message_token: String,
+          retry_state: ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::RetryState?,
+          status: ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::status
         }
 
         type delivery =
@@ -111,6 +126,69 @@ module ArkEmail
             sent_with_ssl: bool
           }
         end
+
+        type retry_state =
+          {
+            attempt: Integer,
+            attempts_remaining: Integer,
+            manual: bool,
+            max_attempts: Integer,
+            processing: bool,
+            next_retry_at: Float?,
+            next_retry_at_iso: Time?
+          }
+
+        class RetryState < ArkEmail::Internal::Type::BaseModel
+          attr_accessor attempt: Integer
+
+          attr_accessor attempts_remaining: Integer
+
+          attr_accessor manual: bool
+
+          attr_accessor max_attempts: Integer
+
+          attr_accessor processing: bool
+
+          attr_accessor next_retry_at: Float?
+
+          attr_accessor next_retry_at_iso: Time?
+
+          def initialize: (
+            attempt: Integer,
+            attempts_remaining: Integer,
+            manual: bool,
+            max_attempts: Integer,
+            processing: bool,
+            ?next_retry_at: Float?,
+            ?next_retry_at_iso: Time?
+          ) -> void
+
+          def to_hash: -> {
+            attempt: Integer,
+            attempts_remaining: Integer,
+            manual: bool,
+            max_attempts: Integer,
+            processing: bool,
+            next_retry_at: Float?,
+            next_retry_at_iso: Time?
+          }
+        end
+
+        type status =
+          :pending | :sent | :softfail | :hardfail | :held | :bounced
+
+        module Status
+          extend ArkEmail::Internal::Type::Enum
+
+          PENDING: :pending
+          SENT: :sent
+          SOFTFAIL: :softfail
+          HARDFAIL: :hardfail
+          HELD: :held
+          BOUNCED: :bounced
+
+          def self?.values: -> ::Array[ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::status]
+        end
       end
     end
   end

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ark-email
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Ark
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-20 00:00:00.000000000 Z
+date: 2026-01-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cgi