ark-email 0.14.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ac63cc3ace8940ad2ecb1f1d70c585a7a18c45210c94df63bbb6b430c3a3b99
-  data.tar.gz: a6c0ec440d80966702b9e0603b5c5831261b1d0fcb95ea819648be26621aa564
+  metadata.gz: 2ab2c267c0272df886fd6e21d8c157bf1534777bdf72da459141654a96e31866
+  data.tar.gz: 84150c3d0ec9b98e472fd7e76f584dd380122359adab410691ab95efb9beb887
 SHA512:
-  metadata.gz: 461156e2cf732613233c7b14eac670447d14515584bfdd1184949109cddcef392565907d1242e5c0e12def831a4eb967ca3c4f533480f9f296c67c9097bd1ab4
-  data.tar.gz: 00333d40915c51936ecddfd10d2d365eda6675a4f7d3aa480720daeec944f8e05c6e6020f4e569d6033e7df5c4f3c2784eb6a39bee2e7a202079bc53f146b54d
+  metadata.gz: 0400a57909216e295f59867461f74717a4815f8e2b3db006d5afe0625e6683c74281069c2db3e3888ce5c7acaccc9f6472a7c7f9952cc1fb3024eb1acf8bb226
+  data.tar.gz: 00aaabff41043bc684fcb450aff04f3367927068d6500fd8e3ff67d62b34bcfbd48cfa3f6b071ea1da24c0094d8198feadb06942e721eef441000769b0f209fb

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.15.0 (2026-01-29)
+
+Full Changelog: [v0.14.0...v0.15.0](https://github.com/ArkHQ-io/ark-ruby/compare/v0.14.0...v0.15.0)
+
+### Features
+
+* **api:** add usage and SendLimit Headers ([82a3ef2](https://github.com/ArkHQ-io/ark-ruby/commit/82a3ef2e4e91a97d9194304c82c1fe3daa9c6d7b))
+* **api:** api update ([5e6a325](https://github.com/ArkHQ-io/ark-ruby/commit/5e6a325e656a4708985e0f9b02adec7947ceff3d))
+* **api:** domain list improvement ([c5dd0aa](https://github.com/ArkHQ-io/ark-ruby/commit/c5dd0aae60d7bd626b13c34dab6a502832fe50d7))
+
+
+### Bug Fixes
+
+* **docs:** fix mcp installation instructions for remote servers ([c5e6779](https://github.com/ArkHQ-io/ark-ruby/commit/c5e677982f2b09306b5cff24e6bb1c563a121f3b))
+
 ## 0.14.0 (2026-01-25)
 
 Full Changelog: [v0.13.0...v0.14.0](https://github.com/ArkHQ-io/ark-ruby/compare/v0.13.0...v0.14.0)

data/README.md

@@ -8,8 +8,8 @@ It is generated with [Stainless](https://www.stainless.com/).
 
 Use the Ark MCP Server to enable AI assistants to interact with this API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.
 
-[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=ark-email-mcp&config=eyJuYW1lIjoiYXJrLWVtYWlsLW1jcCIsInRyYW5zcG9ydCI6InNzZSIsInVybCI6Imh0dHBzOi8vYXJrLW1jcC5zdGxtY3AuY29tL3NzZSJ9)
-[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22ark-email-mcp%22%2C%22type%22%3A%22sse%22%2C%22url%22%3A%22https%3A%2F%2Fark-mcp.stlmcp.com%2Fsse%22%7D)
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=ark-email-mcp&config=eyJuYW1lIjoiYXJrLWVtYWlsLW1jcCIsInRyYW5zcG9ydCI6Imh0dHAiLCJ1cmwiOiJodHRwczovL2Fyay1tY3Auc3RsbWNwLmNvbSIsImhlYWRlcnMiOnsieC1hcmstYXBpLWtleSI6Ik15IEFQSSBLZXkifX0)
+[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22ark-email-mcp%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fark-mcp.stlmcp.com%22%2C%22headers%22%3A%7B%22x-ark-api-key%22%3A%22My%20API%20Key%22%7D%7D)
 
 > Note: You may need to set environment variables in your MCP client.
 
@@ -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.14.0"
+gem "ark-email", "~> 0.15.0"
 ```
 
 <!-- x-release-please-end -->

data/lib/ark_email/client.rb

@@ -42,6 +42,9 @@ module ArkEmail
     # @return [ArkEmail::Resources::Logs]
     attr_reader :logs
 
+    # @return [ArkEmail::Resources::Usage]
+    attr_reader :usage
+
     # @api private
     #
     # @return [Hash{String=>String}]
@@ -101,6 +104,7 @@ module ArkEmail
       @webhooks = ArkEmail::Resources::Webhooks.new(client: self)
       @tracking = ArkEmail::Resources::Tracking.new(client: self)
       @logs = ArkEmail::Resources::Logs.new(client: self)
+      @usage = ArkEmail::Resources::Usage.new(client: self)
     end
   end
 end

data/lib/ark_email/models/dns_record.rb

@@ -3,48 +3,78 @@
 module ArkEmail
   module Models
     class DNSRecord < ArkEmail::Internal::Type::BaseModel
+      # @!attribute full_name
+      #   The complete fully-qualified domain name (FQDN). Use this as a reference to
+      #   verify the record is configured correctly.
+      #
+      #   @return [String]
+      required :full_name, String, api_name: :fullName
+
       # @!attribute name
-      #   DNS record name (hostname)
+      #   The relative hostname to enter in your DNS provider. Most DNS providers
+      #   auto-append the zone name, so you only need to enter this relative part.
+      #
+      #   - `"@"` means the apex/root of the zone (for root domains)
+      #   - `"mail"` for a subdomain like `mail.example.com`
+      #   - `"ark-xyz._domainkey.mail"` for DKIM on a subdomain
       #
       #   @return [String]
       required :name, String
 
       # @!attribute type
-      #   DNS record type
+      #   The DNS record type to create
       #
       #   @return [Symbol, ArkEmail::Models::DNSRecord::Type]
       required :type, enum: -> { ArkEmail::DNSRecord::Type }
 
       # @!attribute value
-      #   DNS record value
+      #   The value to set for the DNS record
       #
       #   @return [String]
       required :value, String
 
       # @!attribute status
-      #   DNS verification status:
+      #   Current verification status of this DNS record:
       #
-      #   - `OK` - Record is correctly configured
-      #   - `Missing` - Record not found in DNS
-      #   - `Invalid` - Record exists but has wrong value
-      #   - `null` - Not yet checked
+      #   - `OK` - Record is correctly configured and verified
+      #   - `Missing` - Record was not found in your DNS
+      #   - `Invalid` - Record exists but has an incorrect value
+      #   - `null` - Record has not been checked yet
       #
       #   @return [Symbol, ArkEmail::Models::DNSRecord::Status, nil]
       optional :status, enum: -> { ArkEmail::DNSRecord::Status }, nil?: true
 
-      # @!method initialize(name:, type:, value:, status: nil)
+      # @!method initialize(full_name:, name:, type:, value:, status: nil)
       #   Some parameter documentations has been truncated, see
       #   {ArkEmail::Models::DNSRecord} for more details.
       #
-      #   @param name [String] DNS record name (hostname)
+      #   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"`
+      #
+      #   @param full_name [String] The complete fully-qualified domain name (FQDN).
+      #
+      #   @param name [String] The relative hostname to enter in your DNS provider.
       #
-      #   @param type [Symbol, ArkEmail::Models::DNSRecord::Type] DNS record type
+      #   @param type [Symbol, ArkEmail::Models::DNSRecord::Type] The DNS record type to create
       #
-      #   @param value [String] DNS record value
+      #   @param value [String] The value to set for the DNS record
       #
-      #   @param status [Symbol, ArkEmail::Models::DNSRecord::Status, nil] DNS verification status:
+      #   @param status [Symbol, ArkEmail::Models::DNSRecord::Status, nil] Current verification status of this DNS record:
 
-      # DNS record type
+      # The DNS record type to create
       #
       # @see ArkEmail::Models::DNSRecord#type
       module Type
@@ -58,12 +88,12 @@ module ArkEmail
         #   @return [Array<Symbol>]
       end
 
-      # DNS verification status:
+      # Current verification status of this DNS record:
       #
-      # - `OK` - Record is correctly configured
-      # - `Missing` - Record not found in DNS
-      # - `Invalid` - Record exists but has wrong value
-      # - `null` - Not yet checked
+      # - `OK` - Record is correctly configured and verified
+      # - `Missing` - Record was not found in your DNS
+      # - `Invalid` - Record exists but has an incorrect value
+      # - `null` - Record has not been checked yet
       #
       # @see ArkEmail::Models::DNSRecord#status
       module Status

data/lib/ark_email/models/domain_create_response.rb

@@ -27,82 +27,174 @@ module ArkEmail
       # @see ArkEmail::Models::DomainCreateResponse#data
       class Data < ArkEmail::Internal::Type::BaseModel
         # @!attribute id
-        #   Domain ID
+        #   Unique domain identifier
         #
-        #   @return [String]
-        required :id, String
+        #   @return [Integer]
+        required :id, Integer
 
         # @!attribute created_at
+        #   Timestamp when the domain was added
         #
         #   @return [Time]
         required :created_at, Time, api_name: :createdAt
 
         # @!attribute dns_records
+        #   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`
         #
-        #   @return [ArkEmail::Models::DomainCreateResponse::Data::DNSRecords]
+        #   @return [ArkEmail::Models::DomainCreateResponse::Data::DNSRecords, nil]
         required :dns_records,
                  -> { ArkEmail::Models::DomainCreateResponse::Data::DNSRecords },
-                 api_name: :dnsRecords
+                 api_name: :dnsRecords,
+                 nil?: true
 
         # @!attribute name
-        #   Domain name
+        #   The domain name used for sending emails
         #
         #   @return [String]
         required :name, String
 
         # @!attribute uuid
+        #   UUID of the domain
         #
         #   @return [String]
         required :uuid, String
 
         # @!attribute verified
-        #   Whether DNS is verified
+        #   Whether all DNS records (SPF, DKIM, Return Path) are correctly configured.
+        #   Domain must be verified before sending emails.
         #
         #   @return [Boolean]
         required :verified, ArkEmail::Internal::Type::Boolean
 
         # @!attribute verified_at
-        #   When the domain was verified (null if not verified)
+        #   Timestamp when the domain ownership was verified, or null if not yet verified
         #
         #   @return [Time, nil]
         optional :verified_at, Time, api_name: :verifiedAt, nil?: true
 
         # @!method initialize(id:, created_at:, dns_records:, name:, uuid:, verified:, verified_at: nil)
-        #   @param id [String] Domain ID
+        #   Some parameter documentations has been truncated, see
+        #   {ArkEmail::Models::DomainCreateResponse::Data} for more details.
         #
-        #   @param created_at [Time]
+        #   @param id [Integer] Unique domain identifier
         #
-        #   @param dns_records [ArkEmail::Models::DomainCreateResponse::Data::DNSRecords]
+        #   @param created_at [Time] Timestamp when the domain was added
         #
-        #   @param name [String] Domain name
+        #   @param dns_records [ArkEmail::Models::DomainCreateResponse::Data::DNSRecords, nil] DNS records that must be added to your domain's DNS settings. Null if records ar
         #
-        #   @param uuid [String]
+        #   @param name [String] The domain name used for sending emails
         #
-        #   @param verified [Boolean] Whether DNS is verified
+        #   @param uuid [String] UUID of the domain
         #
-        #   @param verified_at [Time, nil] When the domain was verified (null if not verified)
+        #   @param verified [Boolean] Whether all DNS records (SPF, DKIM, Return Path) are correctly configured. Domai
+        #
+        #   @param verified_at [Time, nil] Timestamp when the domain ownership was verified, or null if not yet verified
 
         # @see ArkEmail::Models::DomainCreateResponse::Data#dns_records
         class DNSRecords < ArkEmail::Internal::Type::BaseModel
           # @!attribute dkim
+          #   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)
           #
-          #   @return [ArkEmail::Models::DNSRecord]
-          required :dkim, -> { ArkEmail::DNSRecord }
+          #   **Example for root domain `example.com`:**
+          #
+          #   - `name`: `"@"` (DNS shorthand for apex/root)
+          #   - `fullName`: `"example.com"`
+          #
+          #   @return [ArkEmail::Models::DNSRecord, nil]
+          optional :dkim, -> { ArkEmail::DNSRecord }, nil?: true
 
           # @!attribute return_path
+          #   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 [ArkEmail::Models::DNSRecord]
-          required :return_path, -> { ArkEmail::DNSRecord }, api_name: :returnPath
+          #   @return [ArkEmail::Models::DNSRecord, nil]
+          optional :return_path, -> { ArkEmail::DNSRecord }, api_name: :returnPath, nil?: true
 
           # @!attribute spf
+          #   A DNS record that needs to be configured in your domain's DNS settings.
           #
-          #   @return [ArkEmail::Models::DNSRecord]
-          required :spf, -> { ArkEmail::DNSRecord }
+          #   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 [ArkEmail::Models::DNSRecord, nil]
+          optional :spf, -> { ArkEmail::DNSRecord }, nil?: true
+
+          # @!attribute zone
+          #   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`.
+          #
+          #   @return [String, nil]
+          optional :zone, String
 
-          # @!method initialize(dkim:, return_path:, spf:)
-          #   @param dkim [ArkEmail::Models::DNSRecord]
-          #   @param return_path [ArkEmail::Models::DNSRecord]
-          #   @param spf [ArkEmail::Models::DNSRecord]
+          # @!method initialize(dkim: nil, return_path: nil, spf: nil, zone: nil)
+          #   Some parameter documentations has been truncated, see
+          #   {ArkEmail::Models::DomainCreateResponse::Data::DNSRecords} for more details.
+          #
+          #   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`
+          #
+          #   @param dkim [ArkEmail::Models::DNSRecord, nil] A DNS record that needs to be configured in your domain's DNS settings.
+          #
+          #   @param return_path [ArkEmail::Models::DNSRecord, nil] A DNS record that needs to be configured in your domain's DNS settings.
+          #
+          #   @param spf [ArkEmail::Models::DNSRecord, nil] A DNS record that needs to be configured in your domain's DNS settings.
+          #
+          #   @param zone [String] The DNS zone (registrable domain) where records should be added.
         end
       end
     end

data/lib/ark_email/models/domain_list_response.rb

@@ -37,34 +37,33 @@ module ArkEmail
 
         class Domain < ArkEmail::Internal::Type::BaseModel
           # @!attribute id
-          #   Domain ID
+          #   Unique domain identifier
           #
-          #   @return [String]
-          required :id, String
-
-          # @!attribute dns_ok
-          #
-          #   @return [Boolean]
-          required :dns_ok, ArkEmail::Internal::Type::Boolean, api_name: :dnsOk
+          #   @return [Integer]
+          required :id, Integer
 
           # @!attribute name
+          #   The domain name used for sending emails
           #
           #   @return [String]
           required :name, String
 
           # @!attribute verified
+          #   Whether all DNS records (SPF, DKIM, Return Path) are correctly configured.
+          #   Domain must be verified before sending emails.
           #
           #   @return [Boolean]
           required :verified, ArkEmail::Internal::Type::Boolean
 
-          # @!method initialize(id:, dns_ok:, name:, verified:)
-          #   @param id [String] Domain ID
+          # @!method initialize(id:, name:, verified:)
+          #   Some parameter documentations has been truncated, see
+          #   {ArkEmail::Models::DomainListResponse::Data::Domain} for more details.
           #
-          #   @param dns_ok [Boolean]
+          #   @param id [Integer] Unique domain identifier
           #
-          #   @param name [String]
+          #   @param name [String] The domain name used for sending emails
           #
-          #   @param verified [Boolean]
+          #   @param verified [Boolean] Whether all DNS records (SPF, DKIM, Return Path) are correctly configured. Domai
         end
       end
     end

data/lib/ark_email/models/domain_retrieve_response.rb

@@ -27,82 +27,174 @@ module ArkEmail
       # @see ArkEmail::Models::DomainRetrieveResponse#data
       class Data < ArkEmail::Internal::Type::BaseModel
         # @!attribute id
-        #   Domain ID
+        #   Unique domain identifier
         #
-        #   @return [String]
-        required :id, String
+        #   @return [Integer]
+        required :id, Integer
 
         # @!attribute created_at
+        #   Timestamp when the domain was added
         #
         #   @return [Time]
         required :created_at, Time, api_name: :createdAt
 
         # @!attribute dns_records
+        #   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`
         #
-        #   @return [ArkEmail::Models::DomainRetrieveResponse::Data::DNSRecords]
+        #   @return [ArkEmail::Models::DomainRetrieveResponse::Data::DNSRecords, nil]
         required :dns_records,
                  -> { ArkEmail::Models::DomainRetrieveResponse::Data::DNSRecords },
-                 api_name: :dnsRecords
+                 api_name: :dnsRecords,
+                 nil?: true
 
         # @!attribute name
-        #   Domain name
+        #   The domain name used for sending emails
         #
         #   @return [String]
         required :name, String
 
         # @!attribute uuid
+        #   UUID of the domain
         #
         #   @return [String]
         required :uuid, String
 
         # @!attribute verified
-        #   Whether DNS is verified
+        #   Whether all DNS records (SPF, DKIM, Return Path) are correctly configured.
+        #   Domain must be verified before sending emails.
         #
         #   @return [Boolean]
         required :verified, ArkEmail::Internal::Type::Boolean
 
         # @!attribute verified_at
-        #   When the domain was verified (null if not verified)
+        #   Timestamp when the domain ownership was verified, or null if not yet verified
         #
         #   @return [Time, nil]
         optional :verified_at, Time, api_name: :verifiedAt, nil?: true
 
         # @!method initialize(id:, created_at:, dns_records:, name:, uuid:, verified:, verified_at: nil)
-        #   @param id [String] Domain ID
+        #   Some parameter documentations has been truncated, see
+        #   {ArkEmail::Models::DomainRetrieveResponse::Data} for more details.
         #
-        #   @param created_at [Time]
+        #   @param id [Integer] Unique domain identifier
         #
-        #   @param dns_records [ArkEmail::Models::DomainRetrieveResponse::Data::DNSRecords]
+        #   @param created_at [Time] Timestamp when the domain was added
         #
-        #   @param name [String] Domain name
+        #   @param dns_records [ArkEmail::Models::DomainRetrieveResponse::Data::DNSRecords, nil] DNS records that must be added to your domain's DNS settings. Null if records ar
         #
-        #   @param uuid [String]
+        #   @param name [String] The domain name used for sending emails
         #
-        #   @param verified [Boolean] Whether DNS is verified
+        #   @param uuid [String] UUID of the domain
         #
-        #   @param verified_at [Time, nil] When the domain was verified (null if not verified)
+        #   @param verified [Boolean] Whether all DNS records (SPF, DKIM, Return Path) are correctly configured. Domai
+        #
+        #   @param verified_at [Time, nil] Timestamp when the domain ownership was verified, or null if not yet verified
 
         # @see ArkEmail::Models::DomainRetrieveResponse::Data#dns_records
         class DNSRecords < ArkEmail::Internal::Type::BaseModel
           # @!attribute dkim
+          #   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)
           #
-          #   @return [ArkEmail::Models::DNSRecord]
-          required :dkim, -> { ArkEmail::DNSRecord }
+          #   **Example for root domain `example.com`:**
+          #
+          #   - `name`: `"@"` (DNS shorthand for apex/root)
+          #   - `fullName`: `"example.com"`
+          #
+          #   @return [ArkEmail::Models::DNSRecord, nil]
+          optional :dkim, -> { ArkEmail::DNSRecord }, nil?: true
 
           # @!attribute return_path
+          #   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 [ArkEmail::Models::DNSRecord]
-          required :return_path, -> { ArkEmail::DNSRecord }, api_name: :returnPath
+          #   @return [ArkEmail::Models::DNSRecord, nil]
+          optional :return_path, -> { ArkEmail::DNSRecord }, api_name: :returnPath, nil?: true
 
           # @!attribute spf
+          #   A DNS record that needs to be configured in your domain's DNS settings.
           #
-          #   @return [ArkEmail::Models::DNSRecord]
-          required :spf, -> { ArkEmail::DNSRecord }
+          #   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 [ArkEmail::Models::DNSRecord, nil]
+          optional :spf, -> { ArkEmail::DNSRecord }, nil?: true
+
+          # @!attribute zone
+          #   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`.
+          #
+          #   @return [String, nil]
+          optional :zone, String
 
-          # @!method initialize(dkim:, return_path:, spf:)
-          #   @param dkim [ArkEmail::Models::DNSRecord]
-          #   @param return_path [ArkEmail::Models::DNSRecord]
-          #   @param spf [ArkEmail::Models::DNSRecord]
+          # @!method initialize(dkim: nil, return_path: nil, spf: nil, zone: nil)
+          #   Some parameter documentations has been truncated, see
+          #   {ArkEmail::Models::DomainRetrieveResponse::Data::DNSRecords} for more details.
+          #
+          #   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`
+          #
+          #   @param dkim [ArkEmail::Models::DNSRecord, nil] A DNS record that needs to be configured in your domain's DNS settings.
+          #
+          #   @param return_path [ArkEmail::Models::DNSRecord, nil] A DNS record that needs to be configured in your domain's DNS settings.
+          #
+          #   @param spf [ArkEmail::Models::DNSRecord, nil] A DNS record that needs to be configured in your domain's DNS settings.
+          #
+          #   @param zone [String] The DNS zone (registrable domain) where records should be added.
         end
       end
     end