ark-email 0.14.0 → 0.16.0

data/lib/ark_email/models/domain_verify_response.rb

@@ -27,82 +27,174 @@ module ArkEmail
       # @see ArkEmail::Models::DomainVerifyResponse#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::DomainVerifyResponse::Data::DNSRecords]
+        #   @return [ArkEmail::Models::DomainVerifyResponse::Data::DNSRecords, nil]
         required :dns_records,
                  -> { ArkEmail::Models::DomainVerifyResponse::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::DomainVerifyResponse::Data} for more details.
         #
-        #   @param created_at [Time]
+        #   @param id [Integer] Unique domain identifier
         #
-        #   @param dns_records [ArkEmail::Models::DomainVerifyResponse::Data::DNSRecords]
+        #   @param created_at [Time] Timestamp when the domain was added
         #
-        #   @param name [String] Domain name
+        #   @param dns_records [ArkEmail::Models::DomainVerifyResponse::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::DomainVerifyResponse::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::DomainVerifyResponse::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/email_list_response.rb

@@ -5,16 +5,11 @@ module ArkEmail
     # @see ArkEmail::Resources::Emails#list
     class EmailListResponse < ArkEmail::Internal::Type::BaseModel
       # @!attribute id
-      #   Internal message ID
+      #   Unique message identifier (token)
       #
       #   @return [String]
       required :id, String
 
-      # @!attribute token
-      #
-      #   @return [String]
-      required :token, String
-
       # @!attribute from
       #
       #   @return [String]
@@ -58,13 +53,11 @@ module ArkEmail
       #   @return [String, nil]
       optional :tag, String
 
-      # @!method initialize(id:, token:, from:, status:, subject:, timestamp:, timestamp_iso:, to:, tag: nil)
+      # @!method initialize(id:, from:, status:, subject:, timestamp:, timestamp_iso:, to:, tag: nil)
       #   Some parameter documentations has been truncated, see
       #   {ArkEmail::Models::EmailListResponse} for more details.
       #
-      #   @param id [String] Internal message ID
-      #
-      #   @param token [String]
+      #   @param id [String] Unique message identifier (token)
       #
       #   @param from [String]
       #

data/lib/ark_email/models/email_retrieve_deliveries_response.rb

@@ -26,8 +26,14 @@ module ArkEmail
 
       # @see ArkEmail::Models::EmailRetrieveDeliveriesResponse#data
       class Data < ArkEmail::Internal::Type::BaseModel
+        # @!attribute id
+        #   Message identifier (token)
+        #
+        #   @return [String]
+        required :id, String
+
         # @!attribute can_retry_manually
-        #   Whether the message can be manually retried via `POST /emails/{emailId}/retry`.
+        #   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.
         #
@@ -42,18 +48,6 @@ module ArkEmail
         required :deliveries,
                  -> { ArkEmail::Internal::Type::ArrayOf[ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery] }
 
-        # @!attribute message_id
-        #   Internal numeric message ID
-        #
-        #   @return [Integer]
-        required :message_id, Integer, api_name: :messageId
-
-        # @!attribute message_token
-        #   Unique message token for API references
-        #
-        #   @return [String]
-        required :message_token, String, api_name: :messageToken
-
         # @!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.
@@ -77,17 +71,15 @@ module ArkEmail
         #   @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:)
+        # @!method initialize(id:, can_retry_manually:, deliveries:, 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 id [String] Message identifier (token)
         #
-        #   @param deliveries [Array<ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery>] Chronological list of delivery attempts for this message.
+        #   @param can_retry_manually [Boolean] Whether the message can be manually retried via `POST /emails/{id}/retry`.
         #
-        #   @param message_id [Integer] Internal numeric message ID
-        #
-        #   @param message_token [String] Unique message token for API references
+        #   @param deliveries [Array<ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::Delivery>] Chronological list of delivery attempts for this message.
         #
         #   @param retry_state [ArkEmail::Models::EmailRetrieveDeliveriesResponse::Data::RetryState, nil] Information about the current retry state of a message that is queued for delive
         #

data/lib/ark_email/models/email_retrieve_response.rb

@@ -27,19 +27,11 @@ module ArkEmail
       # @see ArkEmail::Models::EmailRetrieveResponse#data
       class Data < ArkEmail::Internal::Type::BaseModel
         # @!attribute id
-        #   Internal message ID
+        #   Unique message identifier (token)
         #
         #   @return [String]
         required :id, String
 
-        # @!attribute token
-        #   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}"
-        #
-        #   @return [String]
-        required :token, String
-
         # @!attribute from
         #   Sender address
         #
@@ -158,13 +150,11 @@ module ArkEmail
         #   @return [String, nil]
         optional :tag, String
 
-        # @!method initialize(id:, token:, from:, scope:, status:, subject:, timestamp:, timestamp_iso:, to:, activity: nil, attachments: nil, deliveries: nil, headers: nil, html_body: nil, message_id: nil, plain_body: nil, raw_message: nil, spam: nil, spam_score: nil, tag: nil)
+        # @!method initialize(id:, from:, scope:, status:, subject:, timestamp:, timestamp_iso:, to:, activity: nil, attachments: nil, deliveries: nil, headers: nil, html_body: nil, message_id: nil, plain_body: nil, raw_message: nil, spam: nil, spam_score: nil, tag: nil)
         #   Some parameter documentations has been truncated, see
         #   {ArkEmail::Models::EmailRetrieveResponse::Data} for more details.
         #
-        #   @param id [String] Internal message ID
-        #
-        #   @param token [String] Unique message token used to retrieve this email via API.
+        #   @param id [String] Unique message identifier (token)
         #
         #   @param from [String] Sender address
         #

data/lib/ark_email/models/email_retry_response.rb

@@ -26,12 +26,20 @@ module ArkEmail
 
       # @see ArkEmail::Models::EmailRetryResponse#data
       class Data < ArkEmail::Internal::Type::BaseModel
+        # @!attribute id
+        #   Email identifier (token)
+        #
+        #   @return [String]
+        required :id, String
+
         # @!attribute message
         #
         #   @return [String]
         required :message, String
 
-        # @!method initialize(message:)
+        # @!method initialize(id:, message:)
+        #   @param id [String] Email identifier (token)
+        #
         #   @param message [String]
       end
     end

data/lib/ark_email/models/email_send_batch_response.rb

@@ -74,20 +74,13 @@ module ArkEmail
 
         class Message < ArkEmail::Internal::Type::BaseModel
           # @!attribute id
-          #   Message ID
+          #   Message identifier (token)
           #
           #   @return [String]
           required :id, String
 
-          # @!attribute token
-          #
-          #   @return [String]
-          required :token, String
-
-          # @!method initialize(id:, token:)
-          #   @param id [String] Message ID
-          #
-          #   @param token [String]
+          # @!method initialize(id:)
+          #   @param id [String] Message identifier (token)
         end
       end
     end

data/lib/ark_email/models/email_send_raw_response.rb

@@ -27,7 +27,7 @@ module ArkEmail
       # @see ArkEmail::Models::EmailSendRawResponse#data
       class Data < ArkEmail::Internal::Type::BaseModel
         # @!attribute id
-        #   Unique message ID (format: msg*{id}*{token})
+        #   Unique message identifier (token)
         #
         #   @return [String]
         required :id, String
@@ -61,7 +61,7 @@ module ArkEmail
         #   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 id [String] Unique message identifier (token)
         #
         #   @param status [Symbol, ArkEmail::Models::EmailSendRawResponse::Data::Status] Current delivery status
         #

data/lib/ark_email/models/email_send_response.rb

@@ -27,7 +27,7 @@ module ArkEmail
       # @see ArkEmail::Models::EmailSendResponse#data
       class Data < ArkEmail::Internal::Type::BaseModel
         # @!attribute id
-        #   Unique message ID (format: msg*{id}*{token})
+        #   Unique message identifier (token)
         #
         #   @return [String]
         required :id, String
@@ -61,7 +61,7 @@ module ArkEmail
         #   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 id [String] Unique message identifier (token)
         #
         #   @param status [Symbol, ArkEmail::Models::EmailSendResponse::Data::Status] Current delivery status
         #

data/lib/ark_email/models/log_entry.rb

@@ -231,7 +231,7 @@ module ArkEmail
       # @see ArkEmail::Models::LogEntry#email
       class Email < ArkEmail::Internal::Type::BaseModel
         # @!attribute id
-        #   Email message ID
+        #   Email message identifier (token)
         #
         #   @return [String, nil]
         optional :id, String
@@ -245,7 +245,7 @@ module ArkEmail
         # @!method initialize(id: nil, recipient_count: nil)
         #   Email-specific data (for email endpoints)
         #
-        #   @param id [String] Email message ID
+        #   @param id [String] Email message identifier (token)
         #
         #   @param recipient_count [Integer, nil] Number of recipients
       end

data/lib/ark_email/models/track_domain.rb

@@ -16,7 +16,8 @@ module ArkEmail
       required :created_at, Time, api_name: :createdAt
 
       # @!attribute dns_ok
-      #   Whether DNS is correctly configured
+      #   Whether the tracking CNAME record is correctly configured. Must be true to use
+      #   tracking features.
       #
       #   @return [Boolean]
       required :dns_ok, ArkEmail::Internal::Type::Boolean, api_name: :dnsOk
@@ -94,11 +95,14 @@ module ArkEmail
       optional :updated_at, Time, api_name: :updatedAt, nil?: true
 
       # @!method initialize(id:, created_at:, dns_ok:, domain_id:, full_name:, name:, ssl_enabled:, track_clicks:, track_opens:, dns_checked_at: nil, dns_error: nil, dns_record: nil, dns_status: nil, excluded_click_domains: nil, updated_at: nil)
+      #   Some parameter documentations has been truncated, see
+      #   {ArkEmail::Models::TrackDomain} for more details.
+      #
       #   @param id [String] Track domain ID
       #
       #   @param created_at [Time] When the track domain was created
       #
-      #   @param dns_ok [Boolean] Whether DNS is correctly configured
+      #   @param dns_ok [Boolean] Whether the tracking CNAME record is correctly configured. Must be true to use t
       #
       #   @param domain_id [String] ID of the parent sending domain
       #

data/lib/ark_email/models/usage_retrieve_params.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module ArkEmail
+  module Models
+    # @see ArkEmail::Resources::Usage#retrieve
+    class UsageRetrieveParams < ArkEmail::Internal::Type::BaseModel
+      extend ArkEmail::Internal::Type::RequestParameters::Converter
+      include ArkEmail::Internal::Type::RequestParameters
+
+      # @!method initialize(request_options: {})
+      #   @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end