ark-email 0.14.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/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

data/lib/ark_email/models/usage_retrieve_response.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+module ArkEmail
+  module Models
+    # @see ArkEmail::Resources::Usage#retrieve
+    class UsageRetrieveResponse < ArkEmail::Internal::Type::BaseModel
+      # @!attribute data
+      #   Current usage and limit information
+      #
+      #   @return [ArkEmail::Models::UsageRetrieveResponse::Data]
+      required :data, -> { ArkEmail::Models::UsageRetrieveResponse::Data }
+
+      # @!attribute meta
+      #
+      #   @return [ArkEmail::Models::APIMeta]
+      required :meta, -> { ArkEmail::APIMeta }
+
+      # @!attribute success
+      #
+      #   @return [Boolean, true]
+      required :success, const: true
+
+      # @!method initialize(data:, meta:, success: true)
+      #   Account usage and limits response
+      #
+      #   @param data [ArkEmail::Models::UsageRetrieveResponse::Data] Current usage and limit information
+      #
+      #   @param meta [ArkEmail::Models::APIMeta]
+      #
+      #   @param success [Boolean, true]
+
+      # @see ArkEmail::Models::UsageRetrieveResponse#data
+      class Data < ArkEmail::Internal::Type::BaseModel
+        # @!attribute billing
+        #   Billing and credit information
+        #
+        #   @return [ArkEmail::Models::UsageRetrieveResponse::Data::Billing, nil]
+        required :billing, -> { ArkEmail::Models::UsageRetrieveResponse::Data::Billing }, nil?: true
+
+        # @!attribute rate_limit
+        #   API rate limit status
+        #
+        #   @return [ArkEmail::Models::UsageRetrieveResponse::Data::RateLimit]
+        required :rate_limit,
+                 -> { ArkEmail::Models::UsageRetrieveResponse::Data::RateLimit },
+                 api_name: :rateLimit
+
+        # @!attribute send_limit
+        #   Email send limit status (hourly cap)
+        #
+        #   @return [ArkEmail::Models::UsageRetrieveResponse::Data::SendLimit, nil]
+        required :send_limit,
+                 -> { ArkEmail::Models::UsageRetrieveResponse::Data::SendLimit },
+                 api_name: :sendLimit,
+                 nil?: true
+
+        # @!method initialize(billing:, rate_limit:, send_limit:)
+        #   Current usage and limit information
+        #
+        #   @param billing [ArkEmail::Models::UsageRetrieveResponse::Data::Billing, nil] Billing and credit information
+        #
+        #   @param rate_limit [ArkEmail::Models::UsageRetrieveResponse::Data::RateLimit] API rate limit status
+        #
+        #   @param send_limit [ArkEmail::Models::UsageRetrieveResponse::Data::SendLimit, nil] Email send limit status (hourly cap)
+
+        # @see ArkEmail::Models::UsageRetrieveResponse::Data#billing
+        class Billing < ArkEmail::Internal::Type::BaseModel
+          # @!attribute auto_recharge
+          #   Auto-recharge configuration
+          #
+          #   @return [ArkEmail::Models::UsageRetrieveResponse::Data::Billing::AutoRecharge]
+          required :auto_recharge,
+                   -> { ArkEmail::Models::UsageRetrieveResponse::Data::Billing::AutoRecharge },
+                   api_name: :autoRecharge
+
+          # @!attribute credit_balance
+          #   Current credit balance as formatted string (e.g., "25.50")
+          #
+          #   @return [String]
+          required :credit_balance, String, api_name: :creditBalance
+
+          # @!attribute credit_balance_cents
+          #   Current credit balance in cents for precise calculations
+          #
+          #   @return [Integer]
+          required :credit_balance_cents, Integer, api_name: :creditBalanceCents
+
+          # @!attribute has_payment_method
+          #   Whether a payment method is configured
+          #
+          #   @return [Boolean]
+          required :has_payment_method, ArkEmail::Internal::Type::Boolean, api_name: :hasPaymentMethod
+
+          # @!method initialize(auto_recharge:, credit_balance:, credit_balance_cents:, has_payment_method:)
+          #   Billing and credit information
+          #
+          #   @param auto_recharge [ArkEmail::Models::UsageRetrieveResponse::Data::Billing::AutoRecharge] Auto-recharge configuration
+          #
+          #   @param credit_balance [String] Current credit balance as formatted string (e.g., "25.50")
+          #
+          #   @param credit_balance_cents [Integer] Current credit balance in cents for precise calculations
+          #
+          #   @param has_payment_method [Boolean] Whether a payment method is configured
+
+          # @see ArkEmail::Models::UsageRetrieveResponse::Data::Billing#auto_recharge
+          class AutoRecharge < ArkEmail::Internal::Type::BaseModel
+            # @!attribute amount
+            #   Amount to recharge when triggered
+            #
+            #   @return [String]
+            required :amount, String
+
+            # @!attribute enabled
+            #   Whether auto-recharge is enabled
+            #
+            #   @return [Boolean]
+            required :enabled, ArkEmail::Internal::Type::Boolean
+
+            # @!attribute threshold
+            #   Balance threshold that triggers recharge
+            #
+            #   @return [String]
+            required :threshold, String
+
+            # @!method initialize(amount:, enabled:, threshold:)
+            #   Auto-recharge configuration
+            #
+            #   @param amount [String] Amount to recharge when triggered
+            #
+            #   @param enabled [Boolean] Whether auto-recharge is enabled
+            #
+            #   @param threshold [String] Balance threshold that triggers recharge
+          end
+        end
+
+        # @see ArkEmail::Models::UsageRetrieveResponse::Data#rate_limit
+        class RateLimit < ArkEmail::Internal::Type::BaseModel
+          # @!attribute limit
+          #   Maximum requests allowed per period
+          #
+          #   @return [Integer]
+          required :limit, Integer
+
+          # @!attribute period
+          #   Time period for the limit
+          #
+          #   @return [Symbol, ArkEmail::Models::UsageRetrieveResponse::Data::RateLimit::Period]
+          required :period, enum: -> { ArkEmail::Models::UsageRetrieveResponse::Data::RateLimit::Period }
+
+          # @!attribute remaining
+          #   Requests remaining in current window
+          #
+          #   @return [Integer]
+          required :remaining, Integer
+
+          # @!attribute reset
+          #   Unix timestamp when the limit resets
+          #
+          #   @return [Integer]
+          required :reset, Integer
+
+          # @!method initialize(limit:, period:, remaining:, reset:)
+          #   API rate limit status
+          #
+          #   @param limit [Integer] Maximum requests allowed per period
+          #
+          #   @param period [Symbol, ArkEmail::Models::UsageRetrieveResponse::Data::RateLimit::Period] Time period for the limit
+          #
+          #   @param remaining [Integer] Requests remaining in current window
+          #
+          #   @param reset [Integer] Unix timestamp when the limit resets
+
+          # Time period for the limit
+          #
+          # @see ArkEmail::Models::UsageRetrieveResponse::Data::RateLimit#period
+          module Period
+            extend ArkEmail::Internal::Type::Enum
+
+            SECOND = :second
+
+            # @!method self.values
+            #   @return [Array<Symbol>]
+          end
+        end
+
+        # @see ArkEmail::Models::UsageRetrieveResponse::Data#send_limit
+        class SendLimit < ArkEmail::Internal::Type::BaseModel
+          # @!attribute approaching
+          #   Whether approaching the limit (>90%)
+          #
+          #   @return [Boolean]
+          required :approaching, ArkEmail::Internal::Type::Boolean
+
+          # @!attribute exceeded
+          #   Whether the limit has been exceeded
+          #
+          #   @return [Boolean]
+          required :exceeded, ArkEmail::Internal::Type::Boolean
+
+          # @!attribute limit
+          #   Maximum emails allowed per hour (null = unlimited)
+          #
+          #   @return [Integer, nil]
+          required :limit, Integer, nil?: true
+
+          # @!attribute period
+          #   Time period for the limit
+          #
+          #   @return [Symbol, ArkEmail::Models::UsageRetrieveResponse::Data::SendLimit::Period]
+          required :period, enum: -> { ArkEmail::Models::UsageRetrieveResponse::Data::SendLimit::Period }
+
+          # @!attribute remaining
+          #   Emails remaining in current period (null if unlimited)
+          #
+          #   @return [Integer, nil]
+          required :remaining, Integer, nil?: true
+
+          # @!attribute resets_at
+          #   ISO timestamp when the limit window resets (top of next hour)
+          #
+          #   @return [Time]
+          required :resets_at, Time, api_name: :resetsAt
+
+          # @!attribute usage_percent
+          #   Usage as a percentage (null if unlimited)
+          #
+          #   @return [Float, nil]
+          required :usage_percent, Float, api_name: :usagePercent, nil?: true
+
+          # @!attribute used
+          #   Emails sent in current period
+          #
+          #   @return [Integer]
+          required :used, Integer
+
+          # @!method initialize(approaching:, exceeded:, limit:, period:, remaining:, resets_at:, usage_percent:, used:)
+          #   Email send limit status (hourly cap)
+          #
+          #   @param approaching [Boolean] Whether approaching the limit (>90%)
+          #
+          #   @param exceeded [Boolean] Whether the limit has been exceeded
+          #
+          #   @param limit [Integer, nil] Maximum emails allowed per hour (null = unlimited)
+          #
+          #   @param period [Symbol, ArkEmail::Models::UsageRetrieveResponse::Data::SendLimit::Period] Time period for the limit
+          #
+          #   @param remaining [Integer, nil] Emails remaining in current period (null if unlimited)
+          #
+          #   @param resets_at [Time] ISO timestamp when the limit window resets (top of next hour)
+          #
+          #   @param usage_percent [Float, nil] Usage as a percentage (null if unlimited)
+          #
+          #   @param used [Integer] Emails sent in current period
+
+          # Time period for the limit
+          #
+          # @see ArkEmail::Models::UsageRetrieveResponse::Data::SendLimit#period
+          module Period
+            extend ArkEmail::Internal::Type::Enum
+
+            HOUR = :hour
+
+            # @!method self.values
+            #   @return [Array<Symbol>]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ark_email/models/webhook_create_params.rb

@@ -75,8 +75,6 @@ module ArkEmail
         MESSAGE_LINK_CLICKED = :MessageLinkClicked
         MESSAGE_LOADED = :MessageLoaded
         DOMAIN_DNS_ERROR = :DomainDNSError
-        SEND_LIMIT_APPROACHING = :SendLimitApproaching
-        SEND_LIMIT_EXCEEDED = :SendLimitExceeded
 
         # @!method self.values
         #   @return [Array<Symbol>]

data/lib/ark_email/models/webhook_create_response.rb

@@ -101,8 +101,6 @@ module ArkEmail
           MESSAGE_LINK_CLICKED = :MessageLinkClicked
           MESSAGE_LOADED = :MessageLoaded
           DOMAIN_DNS_ERROR = :DomainDNSError
-          SEND_LIMIT_APPROACHING = :SendLimitApproaching
-          SEND_LIMIT_EXCEEDED = :SendLimitExceeded
 
           # @!method self.values
           #   @return [Array<Symbol>]

data/lib/ark_email/models/webhook_list_deliveries_params.rb

@@ -70,8 +70,6 @@ module ArkEmail
         MESSAGE_LINK_CLICKED = :MessageLinkClicked
         MESSAGE_LOADED = :MessageLoaded
         DOMAIN_DNS_ERROR = :DomainDNSError
-        SEND_LIMIT_APPROACHING = :SendLimitApproaching
-        SEND_LIMIT_EXCEEDED = :SendLimitExceeded
 
         # @!method self.values
         #   @return [Array<Symbol>]

data/lib/ark_email/models/webhook_list_deliveries_response.rb

@@ -144,8 +144,6 @@ module ArkEmail
           MESSAGE_LINK_CLICKED = :MessageLinkClicked
           MESSAGE_LOADED = :MessageLoaded
           DOMAIN_DNS_ERROR = :DomainDNSError
-          SEND_LIMIT_APPROACHING = :SendLimitApproaching
-          SEND_LIMIT_EXCEEDED = :SendLimitExceeded
 
           # @!method self.values
           #   @return [Array<Symbol>]

data/lib/ark_email/models/webhook_retrieve_delivery_response.rb

@@ -144,8 +144,6 @@ module ArkEmail
           MESSAGE_LINK_CLICKED = :MessageLinkClicked
           MESSAGE_LOADED = :MessageLoaded
           DOMAIN_DNS_ERROR = :DomainDNSError
-          SEND_LIMIT_APPROACHING = :SendLimitApproaching
-          SEND_LIMIT_EXCEEDED = :SendLimitExceeded
 
           # @!method self.values
           #   @return [Array<Symbol>]

data/lib/ark_email/models/webhook_retrieve_response.rb

@@ -101,8 +101,6 @@ module ArkEmail
           MESSAGE_LINK_CLICKED = :MessageLinkClicked
           MESSAGE_LOADED = :MessageLoaded
           DOMAIN_DNS_ERROR = :DomainDNSError
-          SEND_LIMIT_APPROACHING = :SendLimitApproaching
-          SEND_LIMIT_EXCEEDED = :SendLimitExceeded
 
           # @!method self.values
           #   @return [Array<Symbol>]

data/lib/ark_email/models/webhook_test_params.rb

@@ -30,8 +30,6 @@ module ArkEmail
         MESSAGE_LINK_CLICKED = :MessageLinkClicked
         MESSAGE_LOADED = :MessageLoaded
         DOMAIN_DNS_ERROR = :DomainDNSError
-        SEND_LIMIT_APPROACHING = :SendLimitApproaching
-        SEND_LIMIT_EXCEEDED = :SendLimitExceeded
 
         # @!method self.values
         #   @return [Array<Symbol>]

data/lib/ark_email/models/webhook_update_response.rb

@@ -101,8 +101,6 @@ module ArkEmail
           MESSAGE_LINK_CLICKED = :MessageLinkClicked
           MESSAGE_LOADED = :MessageLoaded
           DOMAIN_DNS_ERROR = :DomainDNSError
-          SEND_LIMIT_APPROACHING = :SendLimitApproaching
-          SEND_LIMIT_EXCEEDED = :SendLimitExceeded
 
           # @!method self.values
           #   @return [Array<Symbol>]

data/lib/ark_email/models.rb

@@ -99,6 +99,8 @@ module ArkEmail
 
   TrackingVerifyParams = ArkEmail::Models::TrackingVerifyParams
 
+  UsageRetrieveParams = ArkEmail::Models::UsageRetrieveParams
+
   WebhookCreateParams = ArkEmail::Models::WebhookCreateParams
 
   WebhookDeleteParams = ArkEmail::Models::WebhookDeleteParams

data/lib/ark_email/resources/usage.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module ArkEmail
+  module Resources
+    class Usage
+      # Returns current usage and limit information for your account.
+      #
+      # This endpoint is designed for:
+      #
+      # - **AI agents/MCP servers:** Check constraints before planning batch operations
+      # - **Monitoring dashboards:** Display current usage status
+      # - **Rate limit awareness:** Know remaining capacity before making requests
+      #
+      # **Response includes:**
+      #
+      # - `rateLimit` - API request rate limit (requests per second)
+      # - `sendLimit` - Email sending limit (emails per hour)
+      # - `billing` - Credit balance and auto-recharge configuration
+      #
+      # **Notes:**
+      #
+      # - This request counts against your rate limit
+      # - `sendLimit` may be null if Postal is temporarily unavailable
+      # - `billing` is null if billing is not configured
+      # - Send limit resets at the top of each hour
+      #
+      # @overload retrieve(request_options: {})
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::UsageRetrieveResponse]
+      #
+      # @see ArkEmail::Models::UsageRetrieveParams
+      def retrieve(params = {})
+        @client.request(
+          method: :get,
+          path: "usage",
+          model: ArkEmail::Models::UsageRetrieveResponse,
+          options: params[:request_options]
+        )
+      end
+
+      # @api private
+      #
+      # @param client [ArkEmail::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/ark_email/version.rb

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