haskimail 1.0.0

data/lib/haskimail/http/net_http_transport.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+require "zlib"
+
+require_relative "../errors"
+require_relative "../redacted"
+require_relative "../configuration"
+require_relative "../util"
+
+module Haskimail
+  module HTTP
+    # Header names whose values are never printed.
+    SENSITIVE_HEADERS = %w[x-haskimail-server-token x-haskimail-account-token authorization].freeze
+
+    # Immutable HTTP request handed to a transport. A plain class (not a
+    # Struct) so that no generic accessor — #to_h, #to_a, pp — exposes the token.
+    class Request
+      include Redacted
+
+      attr_reader :method, :url, :headers, :body, :idempotent
+
+      # @param idempotent [Boolean, nil] nil decides by HTTP method; false for
+      #   PUTs with side effects (e.g. re-delivering an inbound message)
+      def initialize(method:, url:, headers:, body:, idempotent: nil)
+        @method = method
+        @url = url
+        @headers = headers
+        @body = body
+        @idempotent = idempotent
+        freeze
+      end
+
+      def idempotent?
+        return idempotent unless idempotent.nil?
+
+        %i[get put delete head options].include?(method)
+      end
+
+      # Sensitive header values are replaced with [FILTERED].
+      def inspect
+        safe = headers.to_h { |name, value| [name, SENSITIVE_HEADERS.include?(name.downcase) ? "[FILTERED]" : value] }
+        "#<#{self.class.name} method=#{method.inspect} url=#{url.inspect} headers=#{safe.inspect} " \
+          "body=#{body ? "#{body.bytesize} bytes" : 'nil'}>"
+      end
+      alias to_s inspect
+
+      # `pp` shows the same redacted text as #inspect.
+      def pretty_print(printer)
+        printer.text(inspect)
+      end
+    end
+
+    # Immutable HTTP response returned by a transport.
+    # `headers` keys are lower-case Strings.
+    class Response
+      # @return [Integer] HTTP status
+      attr_reader :status
+      # @return [Hash{String => String}] lower-case header names
+      attr_reader :headers
+      # @return [String] raw body
+      attr_reader :body
+
+      def initialize(status:, headers:, body:)
+        @status = status
+        @headers = headers
+        @body = body
+        freeze
+      end
+
+      # Same status, headers and body.
+      def ==(other)
+        other.instance_of?(self.class) && [other.status, other.headers, other.body] == [status, headers, body]
+      end
+    end
+
+    # Default transport built on Net::HTTP from the standard library.
+    #
+    # Security properties:
+    # * TLS certificate and hostname verification is always on (VERIFY_PEER);
+    # * TLS 1.2 is the minimum protocol version;
+    # * redirects are never followed (credentials cannot leak to another host);
+    # * a fresh connection per request — the transport is thread-safe.
+    #
+    # Whether a failed request may have reached Haskimail is decided by the
+    # phase it failed in, not by the error class: anything raised while
+    # connecting (DNS, TCP, proxy CONNECT, TLS handshake) means "not sent";
+    # anything raised after the connection is up means "maybe sent".
+    #
+    # Any object with `#call(request, open_timeout:, read_timeout:, write_timeout:)`
+    # returning {Response} can replace it via `transport:` client option.
+    class NetHttpTransport
+      include Redacted
+
+      # Net::HTTPBadResponse and Net::HTTPHeaderSyntaxError are plain
+      # StandardErrors, not Net::ProtocolErrors, so they are listed explicitly.
+      CONNECT_ERRORS = [
+        SocketError, IOError, Net::ProtocolError, Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError, SystemCallError
+      ].freeze
+
+      EXCHANGE_ERRORS = (CONNECT_ERRORS + [Zlib::Error]).freeze
+
+      # Protection against decompression bombs and runaway responses.
+      MAX_RESPONSE_SIZE = 64 * 1024 * 1024
+
+      class ResponseTooLarge < StandardError; end
+
+      METHODS = {
+        get: Net::HTTP::Get,
+        post: Net::HTTP::Post,
+        put: Net::HTTP::Put,
+        patch: Net::HTTP::Patch,
+        delete: Net::HTTP::Delete
+      }.freeze
+      private_constant :CONNECT_ERRORS, :EXCHANGE_ERRORS, :METHODS, :ResponseTooLarge
+
+      # Environment variables checked for a proxy, in this order. http_proxy
+      # is kept as a fallback because Net::HTTP itself uses it for HTTPS too.
+      # Upper-case HTTP_PROXY is ignored on purpose: CGI servers set it from
+      # the request header "Proxy:" ("httpoxy").
+      PROXY_ENV = %w[https_proxy HTTPS_PROXY http_proxy].freeze
+
+      # @param proxy [URI::Generic, false, nil] explicit proxy; false connects
+      #   directly; nil reads {PROXY_ENV} (honouring no_proxy)
+      # @param ca_file [String, nil] PEM bundle trusted IN ADDITION to the system CAs
+      # @param env [Hash] environment (injectable for tests)
+      # @raise [ConfigurationError] for an invalid or https:// proxy in the environment
+      def initialize(proxy: nil, ca_file: nil, env: ENV)
+        from_env = proxy.nil?
+        @proxy = from_env ? self.class.env_proxy(env) : (proxy || nil)
+        @no_proxy = self.class.normalize_no_proxy(env["no_proxy"] || env["NO_PROXY"]) if from_env
+        @cert_store = ca_file && self.class.cert_store(ca_file)
+        freeze
+      end
+
+      # @api private
+      # no_proxy in URI#find_proxy form. Also accepts the conventions of
+      # curl and most other tools: "*" (no proxy at all) and "*.example.com".
+      # @return [String, false] false when every host bypasses the proxy
+      def self.normalize_no_proxy(value)
+        entries = value.to_s.split(/[\s,]+/).reject(&:empty?)
+        return false if entries.include?("*")
+
+        entries.map { |entry| entry.sub(/\A\*\./, ".") }.join(",").freeze
+      end
+
+      # @api private
+      # System CAs plus the given bundle. (Setting Net::HTTP#ca_file instead
+      # would replace the system CAs: a corporate-proxy CA configured
+      # globally would then break direct connections to Haskimail.)
+      # @return [OpenSSL::X509::Store]
+      # @raise [ConfigurationError] when the file is not a readable PEM bundle
+      def self.cert_store(ca_file)
+        store = OpenSSL::X509::Store.new
+        store.set_default_paths
+        store.add_file(ca_file.to_s)
+        store
+      rescue OpenSSL::X509::StoreError, SystemCallError => e
+        raise ConfigurationError, "ca_file #{ca_file.inspect} cannot be loaded: #{e.message}"
+      end
+
+      # @api private
+      # @return [URI::HTTP, nil] validated proxy from the environment
+      def self.env_proxy(env)
+        name = PROXY_ENV.find { |key| !Util.blank?(env[key]) }
+        name && Configuration.parse_proxy(env[name], source: name)
+      end
+
+      # @param request [Request]
+      # @return [Response]
+      def call(request, open_timeout:, read_timeout:, write_timeout:)
+        uri = URI.parse(request.url)
+        net_request = build_request(request, uri)
+        http = build_http(uri, open_timeout, read_timeout, write_timeout)
+        connect(http, uri)
+        begin
+          exchange(http, net_request, uri)
+        ensure
+          http.finish if http.started?
+        end
+      end
+
+      # Shows whether a proxy is used, never its credentials.
+      def inspect
+        "#<#{self.class.name} proxy=#{@proxy ? '[set]' : 'none'}>"
+      end
+
+      private
+
+      # DNS, TCP, proxy CONNECT and TLS handshake: nothing has been sent yet.
+      def connect(http, uri)
+        http.start
+      rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout => e
+        # Read/write timeouts here come from a proxy that never answers CONNECT.
+        raise TimeoutError.new("Connection to #{uri.host} timed out", original_error: e, request_sent: false)
+      rescue OpenSSL::SSL::SSLError => e
+        # Never retried: a certificate problem is not transient and may signal an attack.
+        raise TlsError.new("TLS error talking to #{uri.host}: #{e.message}", original_error: e, request_sent: false)
+      rescue *CONNECT_ERRORS => e
+        raise ConnectionError.new("Could not connect to #{uri.host}: #{e.class}: #{e.message}",
+                                  original_error: e, request_sent: false)
+      end
+
+      # Sends the request and reads the body in chunks, so an oversized
+      # response is cut off early. Any failure here may come after Haskimail
+      # received the request.
+      def exchange(http, net_request, uri)
+        body = +""
+        net_response = http.request(net_request) do |response|
+          response.read_body do |chunk|
+            body << chunk
+            raise ResponseTooLarge if body.bytesize > MAX_RESPONSE_SIZE
+          end
+        end
+        Response.new(status: net_response.code.to_i, headers: net_response.each_header.to_h,
+                     body: body.force_encoding(Encoding::UTF_8))
+      rescue ResponseTooLarge => e
+        raise ConnectionError.new("Response from #{uri.host} exceeds #{MAX_RESPONSE_SIZE} bytes", original_error: e)
+      rescue Net::ReadTimeout, Net::WriteTimeout => e
+        raise TimeoutError.new("Request to #{uri.host} timed out", original_error: e)
+      rescue OpenSSL::SSL::SSLError => e
+        raise TlsError.new("TLS error talking to #{uri.host}: #{e.message}", original_error: e)
+      rescue *EXCHANGE_ERRORS => e
+        raise ConnectionError.new("Connection to #{uri.host} failed: #{e.class}: #{e.message}", original_error: e)
+      end
+
+      def build_http(uri, open_timeout, read_timeout, write_timeout)
+        # Net::HTTP is never left to read the environment itself: it would
+        # use http_proxy unchecked and ignore https_proxy.
+        proxy = @proxy if @proxy && use_proxy?(uri)
+        http = if proxy
+                 Net::HTTP.new(uri.host, uri.port, proxy.host, proxy.port, decode(proxy.user), decode(proxy.password))
+               else
+                 Net::HTTP.new(uri.host, uri.port, nil)
+               end
+        http.use_ssl = true
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        http.min_version = OpenSSL::SSL::TLS1_2_VERSION
+        http.cert_store = @cert_store if @cert_store
+        http.open_timeout = open_timeout
+        http.read_timeout = read_timeout
+        http.write_timeout = write_timeout
+        http.max_retries = 0 # retries are handled by the client with proper rules
+        http
+      end
+
+      def build_request(request, uri)
+        klass = METHODS.fetch(request.method) do
+          raise ValidationError, "Unsupported HTTP method #{request.method.inspect}"
+        end
+        net_request = klass.new(uri.request_uri)
+        request.headers.each { |name, value| net_request[name] = value }
+        net_request.body = request.body if request.body
+        net_request
+      end
+
+      # Same rules as URI#find_proxy: an environment proxy is skipped for
+      # loopback addresses and for hosts matched by no_proxy (names, domain
+      # suffixes, IP ranges in CIDR form). An explicit proxy is always used.
+      def use_proxy?(uri)
+        no_proxy = @no_proxy
+        return true if no_proxy.nil?
+        return false if no_proxy == false
+
+        address = resolve(uri.hostname.to_s)
+        return false if address&.match?(/\A127\.|\A::1\z/)
+
+        # An unresolved name ("") is matched by name only, exactly like nil.
+        URI::Generic.use_proxy?(uri.hostname.to_s, address.to_s, uri.port || 443, no_proxy)
+      end
+
+      def resolve(host)
+        IPSocket.getaddress(host)
+      rescue SocketError
+        nil
+      end
+
+      # Percent-decoding of URL user info ("+" stays "+", unlike form decoding).
+      def decode(value)
+        return nil if value.nil?
+
+        value.b.gsub(/%\h\h/n) { |escape| escape.delete_prefix("%").hex.chr }.force_encoding(Encoding::UTF_8)
+      end
+    end
+  end
+end

data/lib/haskimail/http/response_parser.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "../util"
+
+module Haskimail
+  module HTTP
+    # @api private
+    # Turns an HTTP response into data or into the matching {ApiError}.
+    module ResponseParser
+      # Error class raised for each HTTP status (others: see #error_class).
+      ERROR_CLASSES = {
+        401 => AuthenticationError,
+        403 => ForbiddenError,
+        404 => NotFoundError,
+        413 => PayloadTooLargeError,
+        422 => UnprocessableEntityError,
+        429 => RateLimitError,
+        503 => ServiceUnavailableError
+      }.freeze
+
+      module_function
+
+      # @return [Hash, Array, nil] parsed JSON; nil for an empty or non-JSON body
+      def parse(response)
+        body = response.body.to_s
+        return nil if blank_body?(body)
+
+        Util.parse_json(body)
+      rescue JSON::ParserError # includes JSON::NestingError
+        nil
+      end
+
+      # True for an empty or whitespace-only body.
+      def blank_body?(body)
+        body.to_s.b.strip.empty?
+      end
+
+      # ErrorCode as Integer; the API may also send it as a numeric String.
+      # @return [Integer, nil] nil when absent or not an integral number
+      def error_code(data)
+        value = data.is_a?(Hash) ? data["ErrorCode"] : nil
+        case value
+        when Integer then value
+        when Float then value.to_i if value.finite? && value == value.floor
+        when String then Integer(value.strip, 10, exception: false)
+        end
+      end
+
+      # True when ErrorCode is present but is not a number: the outcome of
+      # the request cannot be determined.
+      def malformed_error_code?(data)
+        data.is_a?(Hash) && !data["ErrorCode"].nil? && error_code(data).nil?
+      end
+
+      # A 2xx carrying a non-zero ErrorCode is still a failure (single objects
+      # only: batch arrays report per-item errors and never raise).
+      def success?(response, data)
+        return false unless (200..299).cover?(response.status)
+        return true unless data.is_a?(Hash) && !data["ErrorCode"].nil?
+
+        error_code(data)&.zero? || false
+      end
+
+      # @return [ApiError]
+      def api_error(response, data)
+        code = error_code(data)
+        message = data.is_a?(Hash) ? data["Message"] : nil
+        status = response.status
+
+        text = "HTTP #{status}"
+        text += " [ErrorCode #{code}]" if code
+        text += ": #{message}" unless message.to_s.empty?
+        text += ": #{response.body.to_s[0, 200]}" if data.nil? && !response.body.to_s.empty?
+
+        error_class(status).new(text, http_status: status, error_code: code, api_message: message,
+                                      response_body: response.body, response_headers: response.headers)
+      end
+
+      # A 2xx whose body cannot be interpreted: not JSON (e.g. a proxy page)
+      # or an ErrorCode that is not a number.
+      # @return [UnexpectedResponseError]
+      def unexpected_body_error(request, response, reason = "a non-JSON body")
+        text = "HTTP #{response.status} with #{reason}: #{response.body.to_s[0, 200]}"
+        unless request.idempotent?
+          text += " (the request may have been executed — for a send, check the message log before re-sending)"
+        end
+        UnexpectedResponseError.new(text, http_status: response.status, response_body: response.body,
+                                          response_headers: response.headers)
+      end
+
+      # @return [Class] the ApiError subclass for an HTTP status
+      def error_class(status)
+        ERROR_CLASSES.fetch(status) do
+          case status
+          when 500.. then ServerError
+          when 200..299 then UnprocessableEntityError
+          else ApiError
+          end
+        end
+      end
+    end
+  end
+end

data/lib/haskimail/http/retry_policy.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "time"
+
+require_relative "../errors"
+
+module Haskimail
+  # HTTP layer: requests, transport, response parsing and retry rules.
+  module HTTP
+    # Decides whether a failed attempt may be repeated and how long to wait.
+    #
+    # The rule of thumb: never repeat a request the server may already have
+    # executed — a duplicate email is worse than an error.
+    class RetryPolicy
+      # Statuses retried for idempotent requests.
+      RETRYABLE_STATUSES = [429, 500, 502, 503, 504].freeze
+      # "Refused before processing": the documentation says to repeat the
+      # request later, so even a POST is safe. 500/502/504 are excluded for
+      # POST — the email may already be accepted.
+      REFUSED_STATUSES = [429, 503].freeze
+      # ErrorCode 36 — "Временная ошибка отправки. Повторите запрос позже":
+      # the email was not accepted.
+      RETRYABLE_ERROR_CODES = [ErrorCodes::TEMPORARY_SENDING_ERROR].freeze
+      # ErrorCode 100 — "Внутренняя ошибка. Повторите запрос позже": repeated
+      # only for idempotent requests (a send may have been processed).
+      IDEMPOTENT_RETRYABLE_ERROR_CODES = [ErrorCodes::INTERNAL_ERROR].freeze
+      # Upper bound for Retry-After, seconds.
+      MAX_RETRY_AFTER = 30
+      # First backoff step, seconds (doubles each attempt).
+      BASE_DELAY = 0.5
+      # Upper bound of the backoff, seconds.
+      MAX_DELAY = 8.0
+
+      attr_reader :max_retries
+
+      # @param max_retries [Integer]
+      # @param random [#rand] source of jitter (injectable for tests)
+      # @param clock [#call] current Time, for Retry-After dates (injectable for tests)
+      def initialize(max_retries:, random: Random, clock: -> { Time.now })
+        @max_retries = max_retries
+        @random = random
+        @clock = clock
+        freeze
+      end
+
+      # @param error_code [Integer, nil] API ErrorCode of the response body
+      def retry_response?(request, response, error_code, attempt)
+        return false if attempt >= max_retries
+
+        if RETRYABLE_STATUSES.include?(response.status)
+          return request.idempotent? || REFUSED_STATUSES.include?(response.status)
+        end
+
+        return false unless response.status == 422
+
+        RETRYABLE_ERROR_CODES.include?(error_code) ||
+          (request.idempotent? && IDEMPOTENT_RETRYABLE_ERROR_CODES.include?(error_code))
+      end
+
+      # TLS failures are never repeated; other network errors are repeated for
+      # idempotent requests, or when the request certainly never left.
+      def retry_error?(request, error, attempt)
+        return false if attempt >= max_retries || error.is_a?(TlsError)
+
+        request.idempotent? || !error.request_sent?
+      end
+
+      # Seconds to wait before attempt number `attempt` (1-based retry count):
+      # Retry-After when the server sent one, otherwise exponential backoff
+      # with "equal jitter".
+      def delay(attempt, response = nil)
+        retry_after(response) || begin
+          base = [BASE_DELAY * (2**(attempt - 1)), MAX_DELAY].min
+          (base / 2) + (@random.rand * base / 2)
+        end
+      end
+
+      private
+
+      # Retry-After as delta-seconds or an HTTP date, capped at MAX_RETRY_AFTER.
+      def retry_after(response)
+        value = response&.headers&.fetch("retry-after", nil).to_s.b.strip
+        return nil if value.empty?
+
+        seconds = value.match?(/\A\d+\z/) ? value.to_i : (Time.httpdate(value) - @clock.call).ceil
+        seconds.clamp(0, MAX_RETRY_AFTER).to_f
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/haskimail/redacted.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Haskimail
+  # @api private
+  # For objects that hold credentials (API token, proxy password): every
+  # generic serializer gets the redacted #inspect text instead of the
+  # instance variables. Covers YAML (Psych), Marshal and JSON, including
+  # ActiveSupport's `as_json`, which would otherwise dump instance variables.
+  module Redacted
+    # YAML shows only the redacted description.
+    def encode_with(coder)
+      coder.scalar = inspect
+    end
+
+    # Never written to caches or dumps.
+    def marshal_dump
+      raise TypeError, "#{self.class.name} holds credentials and cannot be marshalled"
+    end
+
+    # JSON shows only the redacted description.
+    def as_json(*)
+      inspect
+    end
+
+    # JSON shows only the redacted description. (json's RBS types the state
+    # argument of String#to_json too narrowly for a splat.)
+    def to_json(*args)
+      inspect.to_json(*args) # steep:ignore
+    end
+  end
+end

data/lib/haskimail/resources/account_resources.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Haskimail
+  module Resources
+    # Servers (account token): https://haskimail.ru/developer/api/servers-api
+    class Servers < Base
+      # Documented colours (case-insensitive). The API silently stores
+      # "purple" for anything else; the SDK raises instead, so a typo is
+      # caught rather than turned into the wrong colour.
+      COLORS = %w[purple blue turquoise green red orange yellow grey].freeze
+      # Values of TrackLinks besides true/false.
+      TRACK_LINKS = %w[None HtmlAndText HtmlOnly TextOnly].freeze
+      # Live delivers mail, Sandbox never does (set at creation only).
+      DELIVERY_TYPES = %w[Live Sandbox].freeze
+
+      # GET /servers
+      # @return [ApiObject] TotalCount, Servers[]
+      def list(count: nil, offset: nil)
+        check_paging!(count, offset)
+        object(api_get("/servers", query({ count: count, offset: offset }, PAGING)))
+      end
+
+      # The API returns 50 servers per page by default.
+      # @return [Paginator]
+      def each(page_size: 50, &block)
+        paginator = paginate("Servers", page_size: page_size) do |count, offset|
+          api_get("/servers", { "count" => count, "offset" => offset })
+        end
+        run(paginator, block)
+      end
+
+      # GET /servers/{serverid}
+      def get(server_id)
+        object(api_get(path("/servers/%s", server_id)))
+      end
+
+      # POST /servers
+      #
+      #   account.servers.create(name: "Интернет-магазин", color: "purple",
+      #                          track_opens: true, track_links: "HtmlAndText")
+      #
+      # `delivery_type: "Sandbox"` creates a server that never delivers mail;
+      # the type cannot be changed later.
+      def create(params = nil, **fields)
+        payload = validate!(Util.to_api(merge_params(params, fields)))
+        raise ValidationError, "name is required" if Util.blank?(payload["Name"])
+        raise ValidationError, "color is required" if Util.blank?(payload["Color"])
+
+        object(api_post("/servers", payload))
+      end
+
+      # PUT /servers/{serverid} — pass only the fields to change.
+      def update(server_id, params = nil, **fields)
+        payload = validate!(Util.to_api(merge_params(params, fields)))
+        raise ValidationError, "Nothing to update" if payload.empty?
+        if payload.key?("DeliveryType")
+          raise ValidationError, "delivery_type cannot be changed after the server is created"
+        end
+
+        object(api_put(path("/servers/%s", server_id), payload))
+      end
+
+      # DELETE /servers/{serverid} — also deletes its inbound rules.
+      def delete(server_id)
+        object(api_delete(path("/servers/%s", server_id)))
+      end
+
+      # POST /servers/{serverid}/tokens/new — issues an additional server API
+      # token. The plain-text value is returned only once, in this response —
+      # treat it as a secret.
+      #
+      #   account.servers.issue_token(11834, name: "Интеграция 1С")
+      #
+      # @param server_id [Integer]
+      # @param name [String, nil] optional token name
+      # @return [ApiObject] Token, ServerId
+      def issue_token(server_id, name: nil)
+        body = name.nil? ? nil : { "Name" => Util.strip_text(name, "token name") }
+        object(api_post(path("/servers/%s/tokens/new", server_id), body, idempotent: false))
+      end
+
+      private
+
+      def validate!(payload)
+        check_value!(payload, "Color", COLORS) { |value| Util.strip_text(value, "color").downcase }
+        check_value!(payload, "DeliveryType", DELIVERY_TYPES)
+        if payload.key?("TrackLinks") && ![true, false].include?(payload["TrackLinks"])
+          check_value!(payload, "TrackLinks", TRACK_LINKS)
+        end
+        threshold = payload["InboundSpamThreshold"]
+        if threshold && !(threshold.is_a?(Integer) && threshold.between?(0, 30) && (threshold % 5).zero?)
+          raise ValidationError, "inbound_spam_threshold must be 0..30 in steps of 5"
+        end
+
+        payload
+      end
+
+      def check_value!(payload, key, allowed)
+        return unless payload.key?(key)
+
+        value = block_given? ? yield(payload[key]) : payload[key].to_s
+        return if allowed.include?(value)
+
+        raise ValidationError, "#{key} must be one of: #{allowed.join(', ')}"
+      end
+    end
+
+    # Sending domains (account token): https://haskimail.ru/developer/api/domains-api
+    class Domains < Base
+      # GET /domains
+      # @return [ApiObject] TotalCount, Domains[]
+      def list(count: nil, offset: nil)
+        check_paging!(count, offset)
+        object(api_get("/domains", query({ count: count, offset: offset }, PAGING)))
+      end
+
+      # @return [Paginator]
+      def each(page_size: 500, &block)
+        paginator = paginate("Domains", page_size: page_size) do |count, offset|
+          api_get("/domains", { "count" => count, "offset" => offset })
+        end
+        run(paginator, block)
+      end
+
+      # GET /domains/{domainid} — includes the SPF/DKIM records to publish.
+      def get(domain_id)
+        object(api_get(path("/domains/%s", domain_id)))
+      end
+
+      # POST /domains
+      # @param name [String] e.g. "example.com"
+      def create(name)
+        domain = Util.strip_text(name, "Domain name")
+        raise ValidationError, "Domain name must not be blank" if domain.empty?
+
+        object(api_post("/domains", { "Name" => domain }))
+      end
+
+      # DELETE /domains/{domainid} — also removes confirmed addresses on it.
+      def delete(domain_id)
+        object(api_delete(path("/domains/%s", domain_id)))
+      end
+
+      # PUT /domains/{domainid}/verifyDkim — re-checks DNS.
+      def verify_dkim(domain_id)
+        object(api_put(path("/domains/%s/verifyDkim", domain_id)))
+      end
+
+      # PUT /domains/{domainid}/verifyspf — re-checks DNS.
+      def verify_spf(domain_id)
+        object(api_put(path("/domains/%s/verifyspf", domain_id)))
+      end
+    end
+  end
+end