ark-email 0.14.0 → 0.16.0

data/rbi/ark_email/models/domain_verify_response.rbi

@@ -59,47 +59,68 @@ module ArkEmail
             )
           end
 
-        # Domain ID
-        sig { returns(String) }
+        # Unique domain identifier
+        sig { returns(Integer) }
         attr_accessor :id
 
+        # Timestamp when the domain was added
         sig { returns(Time) }
         attr_accessor :created_at
 
+        # DNS records that must be added to your domain's DNS settings. Null if records
+        # are not yet generated.
+        #
+        # **Important:** The `name` field contains the relative hostname that you should
+        # enter in your DNS provider. Most DNS providers auto-append the zone name, so you
+        # only need to enter the relative part.
+        #
+        # For subdomains like `mail.example.com`, the zone is `example.com`, so:
+        #
+        # - SPF `name` would be `mail` (not `@`)
+        # - DKIM `name` would be `ark-xyz._domainkey.mail`
+        # - Return Path `name` would be `psrp.mail`
         sig do
-          returns(ArkEmail::Models::DomainVerifyResponse::Data::DNSRecords)
+          returns(
+            T.nilable(ArkEmail::Models::DomainVerifyResponse::Data::DNSRecords)
+          )
         end
         attr_reader :dns_records
 
         sig do
           params(
             dns_records:
-              ArkEmail::Models::DomainVerifyResponse::Data::DNSRecords::OrHash
+              T.nilable(
+                ArkEmail::Models::DomainVerifyResponse::Data::DNSRecords::OrHash
+              )
           ).void
         end
         attr_writer :dns_records
 
-        # Domain name
+        # The domain name used for sending emails
         sig { returns(String) }
         attr_accessor :name
 
+        # UUID of the domain
         sig { returns(String) }
         attr_accessor :uuid
 
-        # Whether DNS is verified
+        # Whether all DNS records (SPF, DKIM, Return Path) are correctly configured.
+        # Domain must be verified before sending emails.
         sig { returns(T::Boolean) }
         attr_accessor :verified
 
-        # When the domain was verified (null if not verified)
+        # Timestamp when the domain ownership was verified, or null if not yet verified
         sig { returns(T.nilable(Time)) }
         attr_accessor :verified_at
 
         sig do
           params(
-            id: String,
+            id: Integer,
             created_at: Time,
             dns_records:
-              ArkEmail::Models::DomainVerifyResponse::Data::DNSRecords::OrHash,
+              T.nilable(
+                ArkEmail::Models::DomainVerifyResponse::Data::DNSRecords::OrHash
+              ),
             name: String,
             uuid: String,
             verified: T::Boolean,
@@ -107,16 +128,31 @@ module ArkEmail
           ).returns(T.attached_class)
         end
         def self.new(
-          # Domain ID
+          # Unique domain identifier
           id:,
+          # Timestamp when the domain was added
           created_at:,
+          # DNS records that must be added to your domain's DNS settings. Null if records
+          # are not yet generated.
+          #
+          # **Important:** The `name` field contains the relative hostname that you should
+          # enter in your DNS provider. Most DNS providers auto-append the zone name, so you
+          # only need to enter the relative part.
+          #
+          # For subdomains like `mail.example.com`, the zone is `example.com`, so:
+          #
+          # - SPF `name` would be `mail` (not `@`)
+          # - DKIM `name` would be `ark-xyz._domainkey.mail`
+          # - Return Path `name` would be `psrp.mail`
           dns_records:,
-          # Domain name
+          # The domain name used for sending emails
           name:,
+          # UUID of the domain
           uuid:,
-          # Whether DNS is verified
+          # Whether all DNS records (SPF, DKIM, Return Path) are correctly configured.
+          # Domain must be verified before sending emails.
           verified:,
-          # When the domain was verified (null if not verified)
+          # Timestamp when the domain ownership was verified, or null if not yet verified
           verified_at: nil
         )
         end
@@ -124,10 +160,12 @@ module ArkEmail
         sig do
           override.returns(
             {
-              id: String,
+              id: Integer,
               created_at: Time,
               dns_records:
-                ArkEmail::Models::DomainVerifyResponse::Data::DNSRecords,
+                T.nilable(
+                  ArkEmail::Models::DomainVerifyResponse::Data::DNSRecords
+                ),
               name: String,
               uuid: String,
               verified: T::Boolean,
@@ -147,40 +185,163 @@ module ArkEmail
               )
             end
 
-          sig { returns(ArkEmail::DNSRecord) }
+          # A DNS record that needs to be configured in your domain's DNS settings.
+          #
+          # The `name` field contains the relative hostname to enter in your DNS provider
+          # (which auto-appends the zone). The `fullName` field contains the complete
+          # fully-qualified domain name (FQDN) for reference.
+          #
+          # **Example for subdomain `mail.example.com`:**
+          #
+          # - `name`: `"mail"` (what you enter in DNS provider)
+          # - `fullName`: `"mail.example.com"` (the complete hostname)
+          #
+          # **Example for root domain `example.com`:**
+          #
+          # - `name`: `"@"` (DNS shorthand for apex/root)
+          # - `fullName`: `"example.com"`
+          sig { returns(T.nilable(ArkEmail::DNSRecord)) }
           attr_reader :dkim
 
-          sig { params(dkim: ArkEmail::DNSRecord::OrHash).void }
+          sig { params(dkim: T.nilable(ArkEmail::DNSRecord::OrHash)).void }
           attr_writer :dkim
 
-          sig { returns(ArkEmail::DNSRecord) }
+          # A DNS record that needs to be configured in your domain's DNS settings.
+          #
+          # The `name` field contains the relative hostname to enter in your DNS provider
+          # (which auto-appends the zone). The `fullName` field contains the complete
+          # fully-qualified domain name (FQDN) for reference.
+          #
+          # **Example for subdomain `mail.example.com`:**
+          #
+          # - `name`: `"mail"` (what you enter in DNS provider)
+          # - `fullName`: `"mail.example.com"` (the complete hostname)
+          #
+          # **Example for root domain `example.com`:**
+          #
+          # - `name`: `"@"` (DNS shorthand for apex/root)
+          # - `fullName`: `"example.com"`
+          sig { returns(T.nilable(ArkEmail::DNSRecord)) }
           attr_reader :return_path
 
-          sig { params(return_path: ArkEmail::DNSRecord::OrHash).void }
+          sig do
+            params(return_path: T.nilable(ArkEmail::DNSRecord::OrHash)).void
+          end
           attr_writer :return_path
 
-          sig { returns(ArkEmail::DNSRecord) }
+          # A DNS record that needs to be configured in your domain's DNS settings.
+          #
+          # The `name` field contains the relative hostname to enter in your DNS provider
+          # (which auto-appends the zone). The `fullName` field contains the complete
+          # fully-qualified domain name (FQDN) for reference.
+          #
+          # **Example for subdomain `mail.example.com`:**
+          #
+          # - `name`: `"mail"` (what you enter in DNS provider)
+          # - `fullName`: `"mail.example.com"` (the complete hostname)
+          #
+          # **Example for root domain `example.com`:**
+          #
+          # - `name`: `"@"` (DNS shorthand for apex/root)
+          # - `fullName`: `"example.com"`
+          sig { returns(T.nilable(ArkEmail::DNSRecord)) }
           attr_reader :spf
 
-          sig { params(spf: ArkEmail::DNSRecord::OrHash).void }
+          sig { params(spf: T.nilable(ArkEmail::DNSRecord::OrHash)).void }
           attr_writer :spf
 
+          # The DNS zone (registrable domain) where records should be added. This is the
+          # root domain that your DNS provider manages. For `mail.example.com`, the zone is
+          # `example.com`. For `example.co.uk`, the zone is `example.co.uk`.
+          sig { returns(T.nilable(String)) }
+          attr_reader :zone
+
+          sig { params(zone: String).void }
+          attr_writer :zone
+
+          # DNS records that must be added to your domain's DNS settings. Null if records
+          # are not yet generated.
+          #
+          # **Important:** The `name` field contains the relative hostname that you should
+          # enter in your DNS provider. Most DNS providers auto-append the zone name, so you
+          # only need to enter the relative part.
+          #
+          # For subdomains like `mail.example.com`, the zone is `example.com`, so:
+          #
+          # - SPF `name` would be `mail` (not `@`)
+          # - DKIM `name` would be `ark-xyz._domainkey.mail`
+          # - Return Path `name` would be `psrp.mail`
           sig do
             params(
-              dkim: ArkEmail::DNSRecord::OrHash,
-              return_path: ArkEmail::DNSRecord::OrHash,
-              spf: ArkEmail::DNSRecord::OrHash
+              dkim: T.nilable(ArkEmail::DNSRecord::OrHash),
+              return_path: T.nilable(ArkEmail::DNSRecord::OrHash),
+              spf: T.nilable(ArkEmail::DNSRecord::OrHash),
+              zone: String
             ).returns(T.attached_class)
           end
-          def self.new(dkim:, return_path:, spf:)
+          def self.new(
+            # A DNS record that needs to be configured in your domain's DNS settings.
+            #
+            # The `name` field contains the relative hostname to enter in your DNS provider
+            # (which auto-appends the zone). The `fullName` field contains the complete
+            # fully-qualified domain name (FQDN) for reference.
+            #
+            # **Example for subdomain `mail.example.com`:**
+            #
+            # - `name`: `"mail"` (what you enter in DNS provider)
+            # - `fullName`: `"mail.example.com"` (the complete hostname)
+            #
+            # **Example for root domain `example.com`:**
+            #
+            # - `name`: `"@"` (DNS shorthand for apex/root)
+            # - `fullName`: `"example.com"`
+            dkim: nil,
+            # A DNS record that needs to be configured in your domain's DNS settings.
+            #
+            # The `name` field contains the relative hostname to enter in your DNS provider
+            # (which auto-appends the zone). The `fullName` field contains the complete
+            # fully-qualified domain name (FQDN) for reference.
+            #
+            # **Example for subdomain `mail.example.com`:**
+            #
+            # - `name`: `"mail"` (what you enter in DNS provider)
+            # - `fullName`: `"mail.example.com"` (the complete hostname)
+            #
+            # **Example for root domain `example.com`:**
+            #
+            # - `name`: `"@"` (DNS shorthand for apex/root)
+            # - `fullName`: `"example.com"`
+            return_path: nil,
+            # A DNS record that needs to be configured in your domain's DNS settings.
+            #
+            # The `name` field contains the relative hostname to enter in your DNS provider
+            # (which auto-appends the zone). The `fullName` field contains the complete
+            # fully-qualified domain name (FQDN) for reference.
+            #
+            # **Example for subdomain `mail.example.com`:**
+            #
+            # - `name`: `"mail"` (what you enter in DNS provider)
+            # - `fullName`: `"mail.example.com"` (the complete hostname)
+            #
+            # **Example for root domain `example.com`:**
+            #
+            # - `name`: `"@"` (DNS shorthand for apex/root)
+            # - `fullName`: `"example.com"`
+            spf: nil,
+            # The DNS zone (registrable domain) where records should be added. This is the
+            # root domain that your DNS provider manages. For `mail.example.com`, the zone is
+            # `example.com`. For `example.co.uk`, the zone is `example.co.uk`.
+            zone: nil
+          )
           end
 
           sig do
             override.returns(
               {
-                dkim: ArkEmail::DNSRecord,
-                return_path: ArkEmail::DNSRecord,
-                spf: ArkEmail::DNSRecord
+                dkim: T.nilable(ArkEmail::DNSRecord),
+                return_path: T.nilable(ArkEmail::DNSRecord),
+                spf: T.nilable(ArkEmail::DNSRecord),
+                zone: String
               }
             )
           end

data/rbi/ark_email/models/email_list_response.rbi

@@ -11,13 +11,10 @@ module ArkEmail
           )
         end
 
-      # Internal message ID
+      # Unique message identifier (token)
       sig { returns(String) }
       attr_accessor :id
 
-      sig { returns(String) }
-      attr_accessor :token
-
       sig { returns(String) }
       attr_accessor :from
 
@@ -53,7 +50,6 @@ module ArkEmail
       sig do
         params(
           id: String,
-          token: String,
           from: String,
           status: ArkEmail::Models::EmailListResponse::Status::OrSymbol,
           subject: String,
@@ -64,9 +60,8 @@ module ArkEmail
         ).returns(T.attached_class)
       end
       def self.new(
-        # Internal message ID
+        # Unique message identifier (token)
         id:,
-        token:,
         from:,
         # Current delivery status:
         #
@@ -89,7 +84,6 @@ module ArkEmail
         override.returns(
           {
             id: String,
-            token: String,
             from: String,
             status: ArkEmail::Models::EmailListResponse::Status::TaggedSymbol,
             subject: String,

data/rbi/ark_email/models/email_retrieve_deliveries_response.rbi

@@ -61,7 +61,11 @@ module ArkEmail
             )
           end
 
-        # Whether the message can be manually retried via `POST /emails/{emailId}/retry`.
+        # Message identifier (token)
+        sig { returns(String) }
+        attr_accessor :id
+
+        # Whether the message can be manually retried via `POST /emails/{id}/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) }
@@ -78,14 +82,6 @@ module ArkEmail
         end
         attr_accessor :deliveries
 
-        # Internal numeric message ID
-        sig { returns(Integer) }
-        attr_accessor :message_id
-
-        # 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
@@ -124,13 +120,12 @@ module ArkEmail
 
         sig do
           params(
+            id: String,
             can_retry_manually: T::Boolean,
             deliveries:
               T::Array[
                 ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery::OrHash
               ],
-            message_id: Integer,
-            message_token: String,
             retry_state:
               T.nilable(
                 ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::RetryState::OrHash
@@ -140,17 +135,15 @@ module ArkEmail
           ).returns(T.attached_class)
         end
         def self.new(
-          # Whether the message can be manually retried via `POST /emails/{emailId}/retry`.
+          # Message identifier (token)
+          id:,
+          # Whether the message can be manually retried via `POST /emails/{id}/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 numeric message ID
-          message_id:,
-          # 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:,
@@ -169,13 +162,12 @@ module ArkEmail
         sig do
           override.returns(
             {
+              id: String,
               can_retry_manually: T::Boolean,
               deliveries:
                 T::Array[
                   ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery
                 ],
-              message_id: Integer,
-              message_token: String,
               retry_state:
                 T.nilable(
                   ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::RetryState

data/rbi/ark_email/models/email_retrieve_response.rbi

@@ -59,16 +59,10 @@ module ArkEmail
             )
           end
 
-        # Internal message ID
+        # Unique message identifier (token)
         sig { returns(String) }
         attr_accessor :id
 
-        # Unique message token used to retrieve this email via API. Combined with id to
-        # form the full message identifier: msg*{id}*{token} Use this token with GET
-        # /emails/{emailId} where emailId = "msg*{id}*{token}"
-        sig { returns(String) }
-        attr_accessor :token
-
         # Sender address
         sig { returns(String) }
         attr_accessor :from
@@ -230,7 +224,6 @@ module ArkEmail
         sig do
           params(
             id: String,
-            token: String,
             from: String,
             scope:
               ArkEmail::Models::EmailRetrieveResponse::Data::Scope::OrSymbol,
@@ -261,12 +254,8 @@ module ArkEmail
           ).returns(T.attached_class)
         end
         def self.new(
-          # Internal message ID
+          # Unique message identifier (token)
           id:,
-          # Unique message token used to retrieve this email via API. Combined with id to
-          # form the full message identifier: msg*{id}*{token} Use this token with GET
-          # /emails/{emailId} where emailId = "msg*{id}*{token}"
-          token:,
           # Sender address
           from:,
           # Message direction
@@ -318,7 +307,6 @@ module ArkEmail
           override.returns(
             {
               id: String,
-              token: String,
               from: String,
               scope:
                 ArkEmail::Models::EmailRetrieveResponse::Data::Scope::TaggedSymbol,

data/rbi/ark_email/models/email_retry_response.rbi

@@ -59,14 +59,22 @@ module ArkEmail
             )
           end
 
+        # Email identifier (token)
+        sig { returns(String) }
+        attr_accessor :id
+
         sig { returns(String) }
         attr_accessor :message
 
-        sig { params(message: String).returns(T.attached_class) }
-        def self.new(message:)
+        sig { params(id: String, message: String).returns(T.attached_class) }
+        def self.new(
+          # Email identifier (token)
+          id:,
+          message:
+        )
         end
 
-        sig { override.returns({ message: String }) }
+        sig { override.returns({ id: String, message: String }) }
         def to_hash
         end
       end

data/rbi/ark_email/models/email_send_batch_response.rbi

@@ -147,22 +147,18 @@ module ArkEmail
               )
             end
 
-          # Message ID
+          # Message identifier (token)
           sig { returns(String) }
           attr_accessor :id
 
-          sig { returns(String) }
-          attr_accessor :token
-
-          sig { params(id: String, token: String).returns(T.attached_class) }
+          sig { params(id: String).returns(T.attached_class) }
           def self.new(
-            # Message ID
-            id:,
-            token:
+            # Message identifier (token)
+            id:
           )
           end
 
-          sig { override.returns({ id: String, token: String }) }
+          sig { override.returns({ id: String }) }
           def to_hash
           end
         end

data/rbi/ark_email/models/email_send_raw_response.rbi

@@ -59,7 +59,7 @@ module ArkEmail
             )
           end
 
-        # Unique message ID (format: msg*{id}*{token})
+        # Unique message identifier (token)
         sig { returns(String) }
         attr_accessor :id
 
@@ -101,7 +101,7 @@ module ArkEmail
           ).returns(T.attached_class)
         end
         def self.new(
-          # Unique message ID (format: msg*{id}*{token})
+          # Unique message identifier (token)
           id:,
           # Current delivery status
           status:,

data/rbi/ark_email/models/email_send_response.rbi

@@ -59,7 +59,7 @@ module ArkEmail
             )
           end
 
-        # Unique message ID (format: msg*{id}*{token})
+        # Unique message identifier (token)
         sig { returns(String) }
         attr_accessor :id
 
@@ -100,7 +100,7 @@ module ArkEmail
           ).returns(T.attached_class)
         end
         def self.new(
-          # Unique message ID (format: msg*{id}*{token})
+          # Unique message identifier (token)
           id:,
           # Current delivery status
           status:,

data/rbi/ark_email/models/log_entry.rbi

@@ -323,7 +323,7 @@ module ArkEmail
             T.any(ArkEmail::LogEntry::Email, ArkEmail::Internal::AnyHash)
           end
 
-        # Email message ID
+        # Email message identifier (token)
         sig { returns(T.nilable(String)) }
         attr_reader :id
 
@@ -341,7 +341,7 @@ module ArkEmail
           )
         end
         def self.new(
-          # Email message ID
+          # Email message identifier (token)
           id: nil,
           # Number of recipients
           recipient_count: nil

data/rbi/ark_email/models/track_domain.rbi

@@ -16,7 +16,8 @@ module ArkEmail
       sig { returns(Time) }
       attr_accessor :created_at
 
-      # Whether DNS is correctly configured
+      # Whether the tracking CNAME record is correctly configured. Must be true to use
+      # tracking features.
       sig { returns(T::Boolean) }
       attr_accessor :dns_ok
 
@@ -99,7 +100,8 @@ module ArkEmail
         id:,
         # When the track domain was created
         created_at:,
-        # Whether DNS is correctly configured
+        # Whether the tracking CNAME record is correctly configured. Must be true to use
+        # tracking features.
         dns_ok:,
         # ID of the parent sending domain
         domain_id:,

data/rbi/ark_email/models/usage_retrieve_params.rbi

@@ -0,0 +1,27 @@
+# typed: strong
+
+module ArkEmail
+  module Models
+    class UsageRetrieveParams < ArkEmail::Internal::Type::BaseModel
+      extend ArkEmail::Internal::Type::RequestParameters::Converter
+      include ArkEmail::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(ArkEmail::UsageRetrieveParams, ArkEmail::Internal::AnyHash)
+        end
+
+      sig do
+        params(request_options: ArkEmail::RequestOptions::OrHash).returns(
+          T.attached_class
+        )
+      end
+      def self.new(request_options: {})
+      end
+
+      sig { override.returns({ request_options: ArkEmail::RequestOptions }) }
+      def to_hash
+      end
+    end
+  end
+end