haskimail-rails 1.0.0

data/lib/haskimail/resources/messages.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Haskimail
+  module Resources
+    # Sent and received messages, opens and clicks:
+    # https://haskimail.ru/developer/api/messages-api
+    class Messages < Base
+      DEFAULT_PAGE_SIZE = 100
+      MAX_PAGE_SIZE = 500
+      MAX_WINDOW = 10_000 # count + offset limit for outbound, opens and clicks
+      INBOUND_STATUSES = %w[queued processed blocked failed scheduled].freeze
+
+      OUTBOUND_FILTERS = {
+        recipient: "recipient", from_email: "fromemail", tag: "tag", subject: "subject",
+        message_stream: "messagestream", from_date: "fromdate", to_date: "todate"
+      }.freeze
+      EVENT_FILTERS = {
+        recipient: "recipient", tag: "tag", message_stream: "messagestream",
+        from_date: "fromdate", to_date: "todate"
+      }.freeze
+      MESSAGE_EVENT_FILTERS = EVENT_FILTERS.except(:from_date, :to_date).freeze
+      INBOUND_FILTERS = {
+        recipient: "recipient", from_email: "fromemail", subject: "subject", mailbox_hash: "mailboxhash",
+        status: "status", from_date: "fromdate", to_date: "todate"
+      }.freeze
+
+      # ---- Outbound -------------------------------------------------------
+
+      # @return [Hash] { total_count:, messages: [...] } — one record per recipient
+      def outbound(count: DEFAULT_PAGE_SIZE, offset: 0, **filters)
+        api_get(path(:messages), windowed_query(count, offset, filters, OUTBOUND_FILTERS))
+      end
+
+      def each_outbound(page_size: DEFAULT_PAGE_SIZE, **filters, &block)
+        iterate(:messages, page_size, MAX_WINDOW, block, max_page_size: MAX_PAGE_SIZE) do |count, offset|
+          outbound(count: count, offset: offset, **filters)
+        end
+      end
+
+      def outbound_details(message_id)
+        api_get(path(:messages, message_id, :details))
+      end
+
+      # ---- Opens ------------------------------------------------------------
+
+      # @return [Hash] { total_count:, opens: [...] }
+      def opens(count: DEFAULT_PAGE_SIZE, offset: 0, **filters)
+        api_get(path(:messages, :opens), windowed_query(count, offset, filters, EVENT_FILTERS))
+      end
+
+      def each_open(page_size: DEFAULT_PAGE_SIZE, **filters, &block)
+        iterate(:opens, page_size, MAX_WINDOW, block, max_page_size: MAX_PAGE_SIZE) do |count, offset|
+          opens(count: count, offset: offset, **filters)
+        end
+      end
+
+      def opens_for(message_id, count: DEFAULT_PAGE_SIZE, offset: 0, **filters)
+        api_get(path(:messages, :opens, message_id),
+                windowed_query(count, offset, filters, MESSAGE_EVENT_FILTERS))
+      end
+
+      # ---- Clicks -----------------------------------------------------------
+
+      # @return [Hash] { total_count:, clicks: [...] }
+      def clicks(count: DEFAULT_PAGE_SIZE, offset: 0, **filters)
+        api_get(path(:messages, :clicks), windowed_query(count, offset, filters, EVENT_FILTERS))
+      end
+
+      def each_click(page_size: DEFAULT_PAGE_SIZE, **filters, &block)
+        iterate(:clicks, page_size, MAX_WINDOW, block, max_page_size: MAX_PAGE_SIZE) do |count, offset|
+          clicks(count: count, offset: offset, **filters)
+        end
+      end
+
+      def clicks_for(message_id, count: DEFAULT_PAGE_SIZE, offset: 0, **filters)
+        api_get(path(:messages, :clicks, message_id),
+                windowed_query(count, offset, filters, MESSAGE_EVENT_FILTERS))
+      end
+
+      # ---- Inbound ----------------------------------------------------------
+
+      # @return [Hash] { total_count:, inbound_messages: [...] } (last 45 days)
+      def inbound(count: DEFAULT_PAGE_SIZE, offset: 0, **filters)
+        Util.assert_known_keys!(filters.keys, INBOUND_FILTERS.keys, "inbound filter")
+        if filters[:status] && !INBOUND_STATUSES.include?(filters[:status].to_s.downcase)
+          raise ArgumentError, "status must be one of: #{INBOUND_STATUSES.join(', ')}"
+        end
+
+        query = pagination_query(count, offset, max_count: MAX_PAGE_SIZE)
+        filters.each do |key, value|
+          query[INBOUND_FILTERS.fetch(key)] = format_filter(key, value, separator: "T")
+        end
+        query["status"] = query["status"].downcase if query["status"]
+        api_get(path(:messages, :inbound), query)
+      end
+
+      def each_inbound(page_size: DEFAULT_PAGE_SIZE, **filters, &block)
+        iterate(:inbound_messages, page_size, nil, block, max_page_size: MAX_PAGE_SIZE) do |count, offset|
+          inbound(count: count, offset: offset, **filters)
+        end
+      end
+
+      def inbound_details(message_id)
+        api_get(path(:messages, :inbound, message_id, :details))
+      end
+
+      # Delivers a Blocked inbound message to the webhook, skipping block rules and the spam filter.
+      # Never retried automatically: a repeat could post the message to your webhook twice.
+      def bypass_inbound(message_id)
+        api_put(path(:messages, :inbound, message_id, :bypass), idempotent: false)
+      end
+
+      # Re-sends a Failed inbound message to the webhook.
+      def retry_inbound(message_id)
+        api_put(path(:messages, :inbound, message_id, :retry), idempotent: false)
+      end
+
+      private
+
+      def windowed_query(count, offset, filters, allowed)
+        Util.assert_known_keys!(filters.keys, allowed.keys, "filter")
+        query = pagination_query(count, offset, max_count: MAX_PAGE_SIZE, max_window: MAX_WINDOW)
+        filters.each { |key, value| query[allowed.fetch(key)] = format_filter(key, value) }
+        query
+      end
+
+      def format_filter(key, value, separator: " ")
+        return nil if value.nil?
+        return Util.format_datetime(value, separator: separator) if %i[from_date to_date].include?(key)
+
+        value.to_s
+      end
+    end
+  end
+end

data/lib/haskimail/resources/servers.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Haskimail
+  module Resources
+    # Servers (account token): https://haskimail.ru/developer/api/servers-api
+    class Servers < Base
+      DEFAULT_PAGE_SIZE = 50
+      COLORS = %w[purple blue turquoise green red orange yellow grey].freeze
+      TRACK_LINKS = %w[None HtmlAndText HtmlOnly TextOnly].freeze
+      DELIVERY_TYPES = %w[Live Sandbox].freeze
+
+      UPDATABLE = %i[
+        name color smtp_api_activated track_opens track_links inbound_hook_url inbound_domain
+        inbound_spam_threshold raw_email_enabled
+      ].freeze
+      CREATABLE = (UPDATABLE + %i[delivery_type]).freeze
+
+      def get(server_id)
+        api_get(path(:servers, server_id))
+      end
+
+      # @return [Hash] { total_count:, servers: [...] }
+      def list(count: DEFAULT_PAGE_SIZE, offset: 0)
+        api_get(path(:servers), pagination_query(count, offset))
+      end
+
+      def each(page_size: DEFAULT_PAGE_SIZE, &block)
+        iterate(:servers, page_size, nil, block) { |count, offset| list(count: count, offset: offset) }
+      end
+
+      # @example
+      #   account.servers.create(name: "Интернет-магазин", color: "purple", track_links: "HtmlAndText")
+      # @note the response contains server API tokens (:api_tokens) — treat it as a secret.
+      def create(name:, color: "purple", **attributes)
+        require_value!(:name, name)
+        api_post(path(:servers), build(CREATABLE, attributes.merge(name: name, color: color)))
+      end
+
+      # Partial update: send only the attributes to change. DeliveryType cannot be changed.
+      def update(server_id, **attributes)
+        raise ArgumentError, "Nothing to update" if attributes.empty?
+
+        api_put(path(:servers, server_id), build(UPDATABLE, attributes))
+      end
+
+      # Deletes the server together with its inbound rules. Irreversible.
+      def delete(server_id)
+        api_delete(path(:servers, server_id))
+      end
+
+      # Issues an additional server API token. The plain-text value is returned
+      # only once, in this response — treat it as a secret.
+      #
+      # @example
+      #   account.servers.issue_token(11834, name: "Интеграция 1С")
+      # @return [Hash] { token:, server_id: }
+      def issue_token(server_id, name: nil)
+        body = name.nil? ? nil : { "Name" => name.to_s.strip }
+        api_post(path(:servers, server_id, :tokens, :new), body, idempotent: false)
+      end
+
+      private
+
+      def build(allowed, attributes)
+        Util.assert_known_keys!(attributes.keys, allowed, "server attribute")
+        validate!(attributes)
+        Serializer.to_api(attributes.transform_keys(&:to_sym))
+      end
+
+      def validate!(attrs)
+        check_enum!(attrs, :color, COLORS) { |value| value.to_s.downcase }
+        check_enum!(attrs, :delivery_type, DELIVERY_TYPES)
+        check_enum!(attrs, :track_links, TRACK_LINKS) unless [true, false].include?(attrs[:track_links])
+
+        threshold = attrs[:inbound_spam_threshold]
+        return if threshold.nil? || (threshold.is_a?(Integer) && threshold.between?(0, 30) && (threshold % 5).zero?)
+
+        raise ArgumentError, "inbound_spam_threshold must be 0..30 in steps of 5"
+      end
+
+      def check_enum!(attrs, key, allowed)
+        return unless attrs.key?(key)
+
+        value = block_given? ? yield(attrs[key]) : attrs[key].to_s
+        raise ArgumentError, "#{key} must be one of: #{allowed.join(', ')}" unless allowed.include?(value)
+      end
+    end
+  end
+end

data/lib/haskimail/resources/stats.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Haskimail
+  module Resources
+    # Sending statistics: https://haskimail.ru/developer/api/stats-api
+    #
+    # Every method accepts from_date:, to_date: (Date, Time or "YYYY-MM-DD")
+    # and message_stream:.
+    class Stats < Base
+      FILTERS = { from_date: "fromdate", to_date: "todate", message_stream: "messagestream" }.freeze
+
+      # @return [Hash] { sent:, bounced:, opened:, clicked:, unsubscribed:, spam_complaints:,
+      #   bounce_rate:, spam_complaints_rate:, open_rate:, click_rate: }
+      def overview(**filters)
+        fetch(path(:stats), filters)
+      end
+
+      # @return [Hash] { days: [{ date:, sent: }] }
+      def sends(**filters)
+        fetch(path(:stats, :sends), filters)
+      end
+
+      # @return [Hash] { days: [{ date:, hard_bounce:, soft_bounce: }] }
+      def bounces(**filters)
+        fetch(path(:stats, :bounces), filters)
+      end
+
+      # @return [Hash] { days: [{ date:, spam_complaint: }] }
+      def spam_complaints(**filters)
+        fetch(path(:stats, :spam), filters)
+      end
+
+      # @return [Hash] { days: [{ date:, opens: }] }
+      def opens(**filters)
+        fetch(path(:stats, :opens), filters)
+      end
+
+      # @return [Hash] { days: [{ date:, clicks: }] }
+      def clicks(**filters)
+        fetch(path(:stats, :clicks), filters)
+      end
+
+      # @return [Hash] { days: [{ date:, desktop:, mobile:, web_mail:, unknown: }], desktop:, ... }
+      def open_platforms(**filters)
+        fetch(path(:stats, :opens, :platforms), filters)
+      end
+
+      # @return [Hash] { days: [{ date:, platforms... }], desktop:, mobile:, web_mail:, unknown: }
+      def click_platforms(**filters)
+        fetch(path(:stats, :clicks, :platforms), filters)
+      end
+
+      # Client names are data, so they are kept verbatim:
+      # @return [Hash] { days: [{ date: "2026-10-01", counts: { "Apple Mail" => 17 } }],
+      #   totals: { "Apple Mail" => 32 } }
+      def email_clients(**filters)
+        breakdown(path(:stats, :opens, :emailclients), filters)
+      end
+
+      # @return [Hash] { days: [{ date:, counts: { "Chrome" => 9 } }], totals: { "Chrome" => 23 } }
+      def browser_families(**filters)
+        breakdown(path(:stats, :clicks, :browserfamilies), filters)
+      end
+
+      private
+
+      def fetch(api_path, filters)
+        api_get(api_path, query(filters))
+      end
+
+      def breakdown(api_path, filters)
+        raw = connection.get(api_path, query: query(filters)) || {}
+        days = Array(raw["Days"]).map do |day|
+          { date: day["Date"], counts: day.except("Date") }
+        end
+        { days: days, totals: raw.except("Days") }
+      end
+
+      def query(filters)
+        Util.assert_known_keys!(filters.keys, FILTERS.keys, "stats filter")
+        filters.each_with_object({}) do |(key, value), query|
+          next if value.nil?
+
+          query[FILTERS.fetch(key)] = key == :message_stream ? value.to_s : Util.format_date(value)
+        end
+      end
+    end
+  end
+end

data/lib/haskimail/resources/suppressions.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Haskimail
+  module Resources
+    # Suppression lists of a message stream: https://haskimail.ru/developer/api/suppressions-api
+    class Suppressions < Base
+      REASONS = %w[HardBounce SpamComplaint ManualSuppression].freeze
+
+      # @return [Hash] { suppressions: [{ email_address:, suppression_reason:, origin:, created_at: }] }
+      def list(stream_id)
+        api_get(path(:"message-streams", stream_id, :suppressions, :dump))
+      end
+      alias dump list
+
+      # Stops sending to the addresses through this stream.
+      # @return [Hash] { suppressions: [{ email_address:, status: "Suppressed"|"Failed", message: }] }
+      def create(stream_id, email_addresses)
+        api_post(path(:"message-streams", stream_id, :suppressions), body(email_addresses), idempotent: true)
+      end
+      alias suppress create
+
+      # Only manual and hard-bounce suppressions can be removed.
+      # @return [Hash] { suppressions: [{ email_address:, status: "Deleted"|"Failed", message: }] }
+      def delete(stream_id, email_addresses)
+        api_post(path(:"message-streams", stream_id, :suppressions, :delete), body(email_addresses), idempotent: true)
+      end
+      alias unsuppress delete
+
+      private
+
+      def body(email_addresses)
+        list = Array(email_addresses).map { |email| email.to_s.strip }.reject(&:empty?).uniq
+        raise ArgumentError, "At least one email address is required" if list.empty?
+
+        { "Suppressions" => list.map { |email| { "EmailAddress" => email } } }
+      end
+    end
+  end
+end

data/lib/haskimail/resources/templates.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Haskimail
+  module Resources
+    # Templates stored on a server: https://haskimail.ru/developer/api/templates-api
+    class Templates < Base
+      DEFAULT_PAGE_SIZE = 500
+
+      # @param id_or_alias [Integer, String] template ID or name
+      def get(id_or_alias)
+        api_get(path(:templates, id_or_alias))
+      end
+
+      # @return [Hash] { total_count:, templates: [{ template_id:, name: }] }
+      def list(count: DEFAULT_PAGE_SIZE, offset: 0)
+        api_get(path(:templates), pagination_query(count, offset))
+      end
+
+      # @return [Enumerator] all templates, fetched page by page
+      def each(page_size: DEFAULT_PAGE_SIZE, &block)
+        iterate(:templates, page_size, nil, block) { |count, offset| list(count: count, offset: offset) }
+      end
+
+      # @return [Hash] { template_id:, name: }
+      def create(name:, subject: nil, html_body: nil, text_body: nil, associated_server_id: nil)
+        require_value!(:name, name)
+        body = { "Name" => name, "Subject" => subject, "HtmlBody" => html_body,
+                 "TextBody" => text_body, "AssociatedServerId" => associated_server_id }
+        api_post(path(:templates), Util.compact(body))
+      end
+
+      # Replaces the whole template. The API blanks every field that is not sent,
+      # so all four attributes are required. Use #patch to change a single field.
+      def update(id_or_alias, name:, subject:, html_body:, text_body:)
+        require_value!(:name, name)
+        api_put(path(:templates, id_or_alias), {
+                  "Name" => name, "Subject" => subject.to_s, "HtmlBody" => html_body.to_s, "TextBody" => text_body.to_s
+                })
+      end
+
+      # Reads the template and updates only the given attributes.
+      # Not atomic: a concurrent change between the read and the write is overwritten.
+      def patch(id_or_alias, **changes)
+        Util.assert_known_keys!(changes.keys, %i[name subject html_body text_body], "template")
+        current = get(id_or_alias)
+        attributes = %i[name subject html_body text_body].to_h { |key| [key, current[key]] }
+        update(id_or_alias, **attributes, **changes)
+      end
+
+      def delete(id_or_alias)
+        api_delete(path(:templates, id_or_alias))
+      end
+
+      # Renders a template without saving or sending anything.
+      # @return [Hash] { all_content_is_valid:, subject: {...}, html_body: {...}, text_body: {...},
+      #   suggested_template_model: {...} }
+      def validate(subject: nil, html_body: nil, text_body: nil, test_render_model: nil)
+        if [subject, html_body, text_body].all? { |part| Util.blank?(part) }
+          raise ArgumentError, "At least one of subject, html_body or text_body is required"
+        end
+
+        body = Util.compact("Subject" => subject, "HtmlBody" => html_body, "TextBody" => text_body,
+                            "TestRenderModel" => test_render_model)
+        Serializer.from_api(connection.post(path(:templates, :validate), body, idempotent: true))
+      end
+    end
+  end
+end

data/lib/haskimail/resources/webhooks.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Haskimail
+  module Resources
+    # Webhook management: https://haskimail.ru/developer/api/webhooks-api
+    # (for parsing incoming webhook requests see Haskimail::Webhooks)
+    class Webhooks < Base
+      TRIGGERS = %i[delivery bounce spam_complaint open click subscription_change].freeze
+
+      # @return [Hash] { webhooks: [{ id:, url:, message_stream:, triggers: {...} }] }
+      def list
+        api_get(path(:webhooks))
+      end
+
+      def get(webhook_id)
+        api_get(path(:webhooks, webhook_id))
+      end
+
+      # @param triggers [Hash] e.g. { delivery: true, bounce: true } or
+      #   { delivery: { enabled: true } }. Events not listed are disabled.
+      # @example
+      #   client.webhooks.create(url: "https://example.com/haskimail/events",
+      #                          message_stream: "2081", triggers: { delivery: true, bounce: true })
+      def create(url:, triggers:, message_stream: nil)
+        api_post(path(:webhooks), Util.compact(
+                                    "Url" => validate_url!(url),
+                                    "MessageStream" => message_stream&.to_s,
+                                    "Triggers" => build_triggers(triggers)
+                                  ))
+      end
+
+      # Only the given attributes and events change; the stream cannot be changed.
+      def update(webhook_id, url: nil, triggers: nil)
+        body = {}
+        body["Url"] = validate_url!(url) unless url.nil?
+        body["Triggers"] = build_triggers(triggers) unless triggers.nil?
+        raise ArgumentError, "Nothing to update: pass url: and/or triggers:" if body.empty?
+
+        api_put(path(:webhooks, webhook_id), body)
+      end
+
+      def delete(webhook_id)
+        api_delete(path(:webhooks, webhook_id))
+      end
+
+      private
+
+      def validate_url!(url)
+        uri = URI.parse(url.to_s)
+        unless uri.is_a?(URI::HTTP) && uri.host && !uri.host.empty?
+          raise ArgumentError, "url must be an absolute http(s) URL"
+        end
+
+        url.to_s
+      rescue URI::InvalidURIError
+        raise ArgumentError, "url must be an absolute http(s) URL"
+      end
+
+      def build_triggers(triggers)
+        raise ArgumentError, "triggers must be a Hash" unless triggers.is_a?(Hash)
+        raise ArgumentError, "triggers must list at least one event: #{TRIGGERS.join(', ')}" if triggers.empty?
+
+        Util.assert_known_keys!(triggers.keys, TRIGGERS, "trigger")
+        triggers.to_h do |event, setting|
+          enabled = if setting.is_a?(Hash)
+                      setting.fetch(:enabled) do
+                        setting.fetch("Enabled", setting["enabled"])
+                      end
+                    else
+                      setting
+                    end
+          require_boolean!("triggers[:#{event}]", enabled)
+          [Serializer.api_key(event.to_sym), { "Enabled" => enabled }]
+        end
+      end
+    end
+  end
+end

data/lib/haskimail/response_handler.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Haskimail
+  # Turns a Net::HTTPResponse into parsed JSON or raises the matching error.
+  module ResponseHandler
+    MAX_ERROR_BODY = 500
+
+    module_function
+
+    # @return [Hash, Array, nil] parsed JSON body
+    def call(response)
+      status = response.code.to_i
+      headers = response.each_header.to_h
+      body = parse_body(response.body, status)
+
+      if status.between?(200, 299)
+        raise_for_error_code!(body, status, headers)
+        return body
+      end
+
+      error_code = body.is_a?(Hash) ? integer(body["ErrorCode"]) : nil
+      api_message = body.is_a?(Hash) ? body["Message"] : body
+      raise ApiError.for(
+        status: status,
+        error_code: error_code,
+        message: error_message(api_message, status, error_code),
+        body: body,
+        headers: headers
+      )
+    end
+
+    # Some endpoints report failures as {"ErrorCode": N} even with HTTP 200.
+    def raise_for_error_code!(body, status, headers)
+      return unless body.is_a?(Hash)
+
+      code = integer(body["ErrorCode"])
+      return if code.nil? || code.zero?
+
+      raise ApiError.new(error_message(body["Message"], status, code),
+                         status: status, error_code: code, body: body, headers: headers)
+    end
+
+    def integer(value)
+      value.nil? ? nil : Integer(value, exception: false)
+    end
+
+    def parse_body(raw, status)
+      text = raw.to_s.dup.force_encoding(Encoding::UTF_8)
+      return nil if text.strip.empty?
+
+      JSON.parse(text)
+    rescue JSON::ParserError
+      raise InvalidResponseError.new("Haskimail returned invalid JSON (HTTP #{status})", status: status) if status < 300
+
+      text.byteslice(0, MAX_ERROR_BODY).scrub
+    end
+
+    def error_message(api_message, status, error_code)
+      details = ["HTTP #{status}"]
+      details << "ErrorCode #{error_code}" if error_code
+      text = api_message.to_s.strip
+      text = "Haskimail API error" if text.empty?
+      "#{text} (#{details.join(', ')})"
+    end
+  end
+end

data/lib/haskimail/secret.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Haskimail
+  # Wraps a credential so that it cannot leak through #inspect, #to_s,
+  # string interpolation, JSON/ActiveSupport serialization or error trackers
+  # that dump instance variables. Use #reveal to read the real value.
+  class Secret
+    REDACTED = "[REDACTED]"
+
+    def initialize(value)
+      @value = value.to_s.dup.freeze
+      freeze
+    end
+
+    def reveal
+      @value
+    end
+
+    def empty?
+      @value.empty?
+    end
+
+    def ==(other)
+      other.is_a?(Secret) && Webhooks.secure_compare(reveal, other.reveal)
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, @value].hash
+    end
+
+    def inspect
+      "#<#{self.class.name} #{Util.redact(@value)}>"
+    end
+
+    def to_s = REDACTED
+    def as_json(*) = REDACTED
+    def to_json(*) = REDACTED.to_json
+  end
+end

data/lib/haskimail/serializer.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Haskimail
+  # Converts between idiomatic Ruby hashes and the PascalCase JSON of the API.
+  #
+  # Requests: snake_case keys (Symbols or Strings, e.g. from params or a
+  # HashWithIndifferentAccess) are camelized (`:html_body` -> "HtmlBody",
+  # "message_id" -> "MessageID"). Keys that already start with an uppercase
+  # letter ("HtmlBody") are sent verbatim. Two keys that map to the same API
+  # field raise ArgumentError instead of silently overwriting each other.
+  #
+  # Responses: keys become snake_case Symbols ("MessageID" -> :message_id,
+  # "DKIMVerified" -> :dkim_verified).
+  #
+  # Values under "opaque" keys (Metadata, TemplateModel, ...) are user data and
+  # are never transformed in either direction: their keys are template
+  # placeholders such as "{{name}}" or arbitrary metadata names.
+  module Serializer
+    OPAQUE_KEYS = %w[Metadata TemplateModel TestRenderModel SuggestedTemplateModel].freeze
+
+    REQUEST_KEY_OVERRIDES = {
+      "id" => "ID",
+      "message_id" => "MessageID",
+      "content_id" => "ContentID",
+      "server_id" => "ServerID",
+      "source_server_id" => "SourceServerID",
+      "destination_server_id" => "DestinationServerID"
+    }.freeze
+
+    module_function
+
+    def to_api(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(key, val), out|
+          api_key = api_key(key)
+          raise ArgumentError, "Duplicate field #{api_key} (given as #{key.inspect})" if out.key?(api_key)
+
+          out[api_key] = OPAQUE_KEYS.include?(api_key) ? val : to_api(val)
+        end
+      when Array then value.map { |item| to_api(item) }
+      else value
+      end
+    end
+
+    def from_api(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(key, val), out|
+          out[ruby_key(key)] = OPAQUE_KEYS.include?(key.to_s) ? val : from_api(val)
+        end
+      when Array then value.map { |item| from_api(item) }
+      else value
+      end
+    end
+
+    def api_key(key)
+      name = key.to_s
+      return name if name.match?(/\A[A-Z]/)
+
+      REQUEST_KEY_OVERRIDES.fetch(name) do
+        name.split("_").map { |part| part.empty? ? part : part[0].upcase + part[1..] }.join
+      end
+    end
+
+    def ruby_key(key)
+      key.to_s
+         .gsub(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+         .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+         .tr("-", "_")
+         .downcase
+         .to_sym
+    end
+  end
+end