ark-email 0.13.0 → 0.15.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_retrieve_params.rb

@@ -10,10 +10,13 @@ module ArkEmail
       # @!attribute expand
       #   Comma-separated list of fields to include:
       #
+      #   - `full` - Include all expanded fields in a single request
       #   - `content` - HTML and plain text body
       #   - `headers` - Email headers
       #   - `deliveries` - Delivery attempt history
-      #   - `activity` - Opens and clicks
+      #   - `activity` - Opens and clicks tracking data
+      #   - `attachments` - File attachments with content (base64 encoded)
+      #   - `raw` - Complete raw MIME message (base64 encoded)
       #
       #   @return [String, nil]
       optional :expand, String

data/lib/ark_email/models/email_retrieve_response.rb

@@ -89,6 +89,19 @@ module ArkEmail
         #   @return [String]
         required :to, String
 
+        # @!attribute activity
+        #   Opens and clicks tracking data (included if expand=activity)
+        #
+        #   @return [ArkEmail::Models::EmailRetrieveResponse::Data::Activity, nil]
+        optional :activity, -> { ArkEmail::Models::EmailRetrieveResponse::Data::Activity }
+
+        # @!attribute attachments
+        #   File attachments (included if expand=attachments)
+        #
+        #   @return [Array<ArkEmail::Models::EmailRetrieveResponse::Data::Attachment>, nil]
+        optional :attachments,
+                 -> { ArkEmail::Internal::Type::ArrayOf[ArkEmail::Models::EmailRetrieveResponse::Data::Attachment] }
+
         # @!attribute deliveries
         #   Delivery attempt history (included if expand=deliveries)
         #
@@ -120,6 +133,13 @@ module ArkEmail
         #   @return [String, nil]
         optional :plain_body, String, api_name: :plainBody
 
+        # @!attribute raw_message
+        #   Complete raw MIME message, base64 encoded (included if expand=raw). Decode this
+        #   to get the original RFC 2822 formatted email.
+        #
+        #   @return [String, nil]
+        optional :raw_message, String, api_name: :rawMessage
+
         # @!attribute spam
         #   Whether the message was flagged as spam
         #
@@ -138,7 +158,7 @@ module ArkEmail
         #   @return [String, nil]
         optional :tag, String
 
-        # @!method initialize(id:, token:, from:, scope:, status:, subject:, timestamp:, timestamp_iso:, to:, deliveries: nil, headers: nil, html_body: nil, message_id: nil, plain_body: nil, spam: nil, spam_score: nil, tag: nil)
+        # @!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)
         #   Some parameter documentations has been truncated, see
         #   {ArkEmail::Models::EmailRetrieveResponse::Data} for more details.
         #
@@ -160,6 +180,10 @@ module ArkEmail
         #
         #   @param to [String] Recipient address
         #
+        #   @param activity [ArkEmail::Models::EmailRetrieveResponse::Data::Activity] Opens and clicks tracking data (included if expand=activity)
+        #
+        #   @param attachments [Array<ArkEmail::Models::EmailRetrieveResponse::Data::Attachment>] File attachments (included if expand=attachments)
+        #
         #   @param deliveries [Array<ArkEmail::Models::EmailRetrieveResponse::Data::Delivery>] Delivery attempt history (included if expand=deliveries)
         #
         #   @param headers [Hash{Symbol=>String}] Email headers (included if expand=headers)
@@ -170,6 +194,8 @@ module ArkEmail
         #
         #   @param plain_body [String] Plain text body (included if expand=content)
         #
+        #   @param raw_message [String] Complete raw MIME message, base64 encoded (included if expand=raw).
+        #
         #   @param spam [Boolean] Whether the message was flagged as spam
         #
         #   @param spam_score [Float] Spam score (if applicable)
@@ -213,6 +239,156 @@ module ArkEmail
           #   @return [Array<Symbol>]
         end
 
+        # @see ArkEmail::Models::EmailRetrieveResponse::Data#activity
+        class Activity < ArkEmail::Internal::Type::BaseModel
+          # @!attribute clicks
+          #   List of link click events
+          #
+          #   @return [Array<ArkEmail::Models::EmailRetrieveResponse::Data::Activity::Click>, nil]
+          optional :clicks,
+                   -> { ArkEmail::Internal::Type::ArrayOf[ArkEmail::Models::EmailRetrieveResponse::Data::Activity::Click] }
+
+          # @!attribute opens
+          #   List of email open events
+          #
+          #   @return [Array<ArkEmail::Models::EmailRetrieveResponse::Data::Activity::Open>, nil]
+          optional :opens,
+                   -> { ArkEmail::Internal::Type::ArrayOf[ArkEmail::Models::EmailRetrieveResponse::Data::Activity::Open] }
+
+          # @!method initialize(clicks: nil, opens: nil)
+          #   Opens and clicks tracking data (included if expand=activity)
+          #
+          #   @param clicks [Array<ArkEmail::Models::EmailRetrieveResponse::Data::Activity::Click>] List of link click events
+          #
+          #   @param opens [Array<ArkEmail::Models::EmailRetrieveResponse::Data::Activity::Open>] List of email open events
+
+          class Click < ArkEmail::Internal::Type::BaseModel
+            # @!attribute ip_address
+            #   IP address of the clicker
+            #
+            #   @return [String, nil]
+            optional :ip_address, String, api_name: :ipAddress
+
+            # @!attribute timestamp
+            #   Unix timestamp of the click event
+            #
+            #   @return [Float, nil]
+            optional :timestamp, Float
+
+            # @!attribute timestamp_iso
+            #   ISO 8601 timestamp of the click event
+            #
+            #   @return [Time, nil]
+            optional :timestamp_iso, Time, api_name: :timestampIso
+
+            # @!attribute url
+            #   URL that was clicked
+            #
+            #   @return [String, nil]
+            optional :url, String
+
+            # @!attribute user_agent
+            #   User agent of the email client
+            #
+            #   @return [String, nil]
+            optional :user_agent, String, api_name: :userAgent
+
+            # @!method initialize(ip_address: nil, timestamp: nil, timestamp_iso: nil, url: nil, user_agent: nil)
+            #   @param ip_address [String] IP address of the clicker
+            #
+            #   @param timestamp [Float] Unix timestamp of the click event
+            #
+            #   @param timestamp_iso [Time] ISO 8601 timestamp of the click event
+            #
+            #   @param url [String] URL that was clicked
+            #
+            #   @param user_agent [String] User agent of the email client
+          end
+
+          class Open < ArkEmail::Internal::Type::BaseModel
+            # @!attribute ip_address
+            #   IP address of the opener
+            #
+            #   @return [String, nil]
+            optional :ip_address, String, api_name: :ipAddress
+
+            # @!attribute timestamp
+            #   Unix timestamp of the open event
+            #
+            #   @return [Float, nil]
+            optional :timestamp, Float
+
+            # @!attribute timestamp_iso
+            #   ISO 8601 timestamp of the open event
+            #
+            #   @return [Time, nil]
+            optional :timestamp_iso, Time, api_name: :timestampIso
+
+            # @!attribute user_agent
+            #   User agent of the email client
+            #
+            #   @return [String, nil]
+            optional :user_agent, String, api_name: :userAgent
+
+            # @!method initialize(ip_address: nil, timestamp: nil, timestamp_iso: nil, user_agent: nil)
+            #   @param ip_address [String] IP address of the opener
+            #
+            #   @param timestamp [Float] Unix timestamp of the open event
+            #
+            #   @param timestamp_iso [Time] ISO 8601 timestamp of the open event
+            #
+            #   @param user_agent [String] User agent of the email client
+          end
+        end
+
+        class Attachment < ArkEmail::Internal::Type::BaseModel
+          # @!attribute content_type
+          #   MIME type of the attachment
+          #
+          #   @return [String]
+          required :content_type, String, api_name: :contentType
+
+          # @!attribute data
+          #   Base64 encoded attachment content. Decode this to get the raw file bytes.
+          #
+          #   @return [String]
+          required :data, String
+
+          # @!attribute filename
+          #   Original filename of the attachment
+          #
+          #   @return [String]
+          required :filename, String
+
+          # @!attribute hash_
+          #   SHA256 hash of the attachment content for verification
+          #
+          #   @return [String]
+          required :hash_, String, api_name: :hash
+
+          # @!attribute size
+          #   Size of the attachment in bytes
+          #
+          #   @return [Integer]
+          required :size, Integer
+
+          # @!method initialize(content_type:, data:, filename:, hash_:, size:)
+          #   Some parameter documentations has been truncated, see
+          #   {ArkEmail::Models::EmailRetrieveResponse::Data::Attachment} for more details.
+          #
+          #   An email attachment retrieved from a sent message
+          #
+          #   @param content_type [String] MIME type of the attachment
+          #
+          #   @param data [String] Base64 encoded attachment content. Decode this to get the raw file bytes.
+          #
+          #   @param filename [String] Original filename of the attachment
+          #
+          #   @param hash_ [String] SHA256 hash of the attachment content for verification
+          #
+          #   @param size [Integer] Size of the attachment in bytes
+        end
+
         class Delivery < ArkEmail::Internal::Type::BaseModel
           # @!attribute id
           #   Delivery attempt ID