haskimail-rails 1.0.0

data/lib/haskimail/connection.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+
+module Haskimail
+  # HTTP transport with JSON (de)serialization, error mapping and retries with
+  # exponential backoff and jitter. Thread-safe and fork-safe.
+  #
+  # Retry policy (designed so that an email is never sent twice):
+  # * the TCP/TLS connection could not be opened (DNS, refused, open timeout):
+  #   nothing was sent, so any request is retried;
+  # * the request may have reached the server (read timeout, reset, 5xx, 429):
+  #   only idempotent requests are retried — GET, PUT and explicitly marked
+  #   calls. POST (sending!) and DELETE are never retried in this case.
+  class Connection
+    IDEMPOTENT_METHODS = %w[GET HEAD OPTIONS PUT].freeze
+
+    # Errors from opening the connection (Net::HTTP#start): no request byte was sent.
+    CONNECT_ERRORS = [
+      Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ENETUNREACH, Errno::EADDRNOTAVAIL,
+      Errno::ECONNRESET, Errno::ETIMEDOUT, SocketError, Net::OpenTimeout
+    ].freeze
+
+    # Errors while the request was in flight: it may already have been processed.
+    TRANSPORT_ERRORS = [
+      Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ENETUNREACH, Errno::EADDRNOTAVAIL,
+      Errno::ECONNRESET, Errno::EPIPE, Errno::ECONNABORTED, Errno::ETIMEDOUT, SocketError,
+      EOFError, IOError, Net::ReadTimeout, Net::WriteTimeout, Net::HTTPBadResponse, Timeout::Error
+    ].freeze
+
+    THREAD_KEY = :__haskimail_http_connections
+
+    # A pooled socket idle for longer than this is reopened before use, so that
+    # reconnecting happens in the (retry-safe) connect phase instead of inside
+    # Net::HTTP#request. Must stay below Net::HTTP#keep_alive_timeout.
+    MAX_IDLE_SECONDS = 1.5
+    KEEP_ALIVE_TIMEOUT = 2
+
+    # Internal marker: the connection could not be opened (see #open_connection).
+    class ConnectFailure < StandardError; end
+    private_constant :ConnectFailure
+
+    attr_reader :config
+
+    def initialize(token:, token_header:, config:)
+      @token = Secret.new(Util.validate_token!(token, token_header))
+      @token_header = token_header
+      @config = config
+      @base_uri = config.base_uri
+      @pool_key = [@base_uri.host, @base_uri.port, config.open_timeout, config.read_timeout,
+                   config.write_timeout].freeze
+    end
+
+    def get(path, query: nil)
+      request(:get, path, query: query)
+    end
+
+    def post(path, body = nil, idempotent: false)
+      request(:post, path, body: body, idempotent: idempotent)
+    end
+
+    def put(path, body = nil, idempotent: true)
+      request(:put, path, body: body, idempotent: idempotent)
+    end
+
+    def patch(path, body = nil)
+      request(:patch, path, body: body, idempotent: true)
+    end
+
+    def delete(path)
+      request(:delete, path, idempotent: false)
+    end
+
+    # @return [Hash, Array, nil] the parsed JSON body (keys as returned by the API)
+    def request(method, path, query: nil, body: nil, idempotent: nil)
+      verb = method.to_s.upcase
+      idempotent = IDEMPOTENT_METHODS.include?(verb) if idempotent.nil?
+      uri = build_uri(path, query)
+      payload = body.nil? ? nil : JSON.generate(body)
+      with_retries(idempotent) { |attempt| send_once(verb, uri, payload, attempt) }
+    end
+
+    def inspect
+      "#<#{self.class.name} base_url=#{@base_uri} #{@token_header}=#{Util.redact(@token.reveal).inspect}>"
+    end
+    alias to_s inspect
+
+    private
+
+    def with_retries(idempotent)
+      attempt = 0
+
+      begin
+        attempt += 1
+        yield attempt
+      rescue ConnectFailure => e
+        retry if retry_after_pause?(attempt)
+        raise wrap_network_error(e.cause)
+      rescue *TRANSPORT_ERRORS => e
+        discard_connection
+        retry if idempotent && retry_after_pause?(attempt)
+        raise wrap_network_error(e)
+      rescue OpenSSL::SSL::SSLError => e
+        discard_connection
+        # A dropped TLS session may surface as SSLError; certificate problems are never retried.
+        retry if idempotent && !e.message.match?(/certificate|verify/i) && retry_after_pause?(attempt)
+        raise ConnectionError, "TLS error while talking to Haskimail: #{e.message}"
+      rescue ApiError => e
+        retry if idempotent && e.retryable? && retry_after_pause?(attempt, e.headers["retry-after"])
+        raise
+      end
+    end
+
+    def build_uri(path, query)
+      uri = @base_uri.dup
+      uri.path = "#{@base_uri.path.chomp('/')}#{path}"
+      params = query&.compact
+      uri.query = URI.encode_www_form(params) if params && !params.empty?
+      uri
+    end
+
+    def send_once(verb, uri, payload, attempt)
+      http = open_connection
+      response = instrument(verb, uri, attempt) { perform(http, verb, uri, payload) }
+      touch_connection
+      ResponseHandler.call(response)
+    end
+
+    def perform(http, verb, uri, payload)
+      request = Net::HTTPGenericRequest.new(verb, !payload.nil?, verb != "HEAD", uri.request_uri)
+      default_headers(payload).each { |name, value| request[name] = value }
+      request.body = payload if payload
+      http.request(request)
+    ensure
+      close_quietly(http) unless config.persistent_connections
+    end
+
+    # Opening the socket is the only phase that is guaranteed to happen before
+    # the request is written, so only its failures are marked as safe to retry.
+    def open_connection
+      config.persistent_connections ? pooled_http : build_http.tap(&:start)
+    rescue *CONNECT_ERRORS
+      raise ConnectFailure
+    end
+
+    def default_headers(payload)
+      headers = {
+        "Accept" => "application/json",
+        "User-Agent" => user_agent,
+        @token_header => @token.reveal
+      }
+      headers["Content-Type"] = "application/json; charset=utf-8" if payload
+      headers
+    end
+
+    def user_agent
+      @user_agent ||= [
+        "haskimail-rails/#{VERSION}",
+        "ruby/#{RUBY_VERSION}",
+        "(#{RUBY_PLATFORM})",
+        config.user_agent_suffix
+      ].compact.join(" ")
+    end
+
+    def build_http
+      http = Net::HTTP.new(@base_uri.host, @base_uri.port)
+      http.use_ssl = true
+      http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+      http.min_version = OpenSSL::SSL::TLS1_2_VERSION
+      http.open_timeout = config.open_timeout
+      http.read_timeout = config.read_timeout
+      http.write_timeout = config.write_timeout
+      http.keep_alive_timeout = KEEP_ALIVE_TIMEOUT
+      # Net::HTTP silently re-sends idempotent requests (including PUT and
+      # DELETE) once after a timeout or reset. Retries are decided here instead.
+      http.max_retries = 0
+      http
+    end
+
+    # One keep-alive connection per thread (more precisely per fiber, since
+    # Thread#[] is fiber-local — so concurrent fibers never share a socket) and
+    # per endpoint/timeouts. The PID check makes it fork-safe: a Puma/Unicorn
+    # worker never reuses its parent's TLS socket. For fiber-per-request servers
+    # (Falcon) set persistent_connections = false.
+    def pooled_http
+      pool = (Thread.current[THREAD_KEY] ||= {})
+      pid, http, last_used = pool[@pool_key]
+      return http if pid == Process.pid && http&.started? && monotonic_now - last_used < MAX_IDLE_SECONDS
+
+      close_quietly(http) if pid == Process.pid
+      pool.delete(@pool_key)
+      http = build_http
+      http.start
+      pool[@pool_key] = [Process.pid, http, monotonic_now]
+      http
+    end
+
+    def touch_connection
+      entry = config.persistent_connections && Thread.current[THREAD_KEY]&.[](@pool_key)
+      entry[2] = monotonic_now if entry
+    end
+
+    def discard_connection
+      return unless config.persistent_connections
+
+      pid, http = Thread.current[THREAD_KEY]&.delete(@pool_key)
+      close_quietly(http) if pid == Process.pid
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def close_quietly(http)
+      http.finish if http&.started?
+    rescue IOError, SystemCallError, OpenSSL::SSL::SSLError
+      nil
+    end
+
+    def retry_after_pause?(attempt, retry_after = nil)
+      return false if attempt > config.max_retries.to_i
+
+      pause(retry_delay(attempt, retry_after))
+      true
+    end
+
+    def retry_delay(attempt, retry_after)
+      max = config.retry_max_delay.to_f
+      server_hint = Float(retry_after, exception: false)
+      return server_hint.clamp(0.0, max) if server_hint
+
+      exponential = [config.retry_base_delay.to_f * (2**(attempt - 1)), max].min
+      (exponential / 2) + (rand * exponential / 2) # "equal jitter"
+    end
+
+    def pause(seconds)
+      sleep(seconds) if seconds.positive?
+    end
+
+    def wrap_network_error(error)
+      klass = error.is_a?(Timeout::Error) || error.is_a?(Errno::ETIMEDOUT) ? TimeoutError : ConnectionError
+      klass.new("Could not reach Haskimail (#{error.class}: #{error.message})")
+    end
+
+    def instrument(verb, uri, attempt)
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      payload = { method: verb, path: uri.path, attempt: attempt }
+      response = if defined?(ActiveSupport::Notifications)
+                   ActiveSupport::Notifications.instrument("request.haskimail", payload) do
+                     yield.tap { |res| payload[:status] = res.code.to_i }
+                   end
+                 else
+                   yield
+                 end
+      log(verb, uri, response.code, started)
+      response
+    end
+
+    def log(verb, uri, code, started)
+      return unless config.logger
+
+      elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round
+      config.logger.info("[Haskimail] #{verb} #{uri.path} -> #{code} (#{elapsed}ms)")
+    end
+  end
+end

data/lib/haskimail/errors.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Haskimail
+  # Base class for every error raised by this library.
+  class Error < StandardError; end
+
+  # Missing or invalid client configuration (no token, non-HTTPS base URL, ...).
+  class ConfigurationError < Error; end
+
+  # Network-level failure: the API could not be reached or the connection broke.
+  class ConnectionError < Error; end
+
+  # The connection or the response timed out.
+  class TimeoutError < ConnectionError; end
+
+  # The API answered with something that is not valid JSON.
+  class InvalidResponseError < Error
+    attr_reader :status
+
+    def initialize(message = nil, status: nil)
+      super(message)
+      @status = status
+    end
+  end
+
+  # Numeric `ErrorCode` values documented at https://haskimail.ru/developer/api/overview.
+  module ErrorCodes
+    INVALID_API_TOKEN = 10
+    NOT_FOUND = 12
+    INTERNAL_ERROR = 100
+    MISSING_REQUIRED_FIELDS = 3
+    SENDING_NOT_ALLOWED = 4
+    INVALID_EMAIL = 6
+    ACTION_FORBIDDEN = 15
+    ATTACHMENT_TOO_LARGE = 26
+    ATTACHMENT_TYPE_NOT_ALLOWED = 33
+    SENDING_UNAVAILABLE = 35
+    TEMPORARY_SEND_ERROR = 36
+    INVALID_HEADERS = 40
+    SENDER_NOT_CONFIRMED = 52
+    INVALID_BATCH = 300
+    MODERATION_SENDER_NOT_CONFIRMED = 400
+    MODERATION_RECIPIENT_NOT_CONFIRMED = 412
+    MESSAGE_NOT_FOUND = 701
+    TEMPLATE_SERVER_MISMATCH = 510
+    DOMAIN_ALREADY_TAKEN = 512
+    INBOUND_DOMAIN_WITHOUT_MX = 610
+    TEMPLATE_NOT_FOUND = 1101
+    TEMPLATE_VALIDATION_INPUT_INVALID = 1120
+    MESSAGE_STREAM_INVALID = 1226
+    INBOUND_STREAM_NOT_ARCHIVABLE = 1229
+    INBOUND_STREAM_NOT_SENDABLE = 1236
+  end
+
+  # The API answered with a non-success HTTP status or a non-zero `ErrorCode`.
+  class ApiError < Error
+    RETRYABLE_STATUSES = [429, 500, 502, 503, 504].freeze
+
+    attr_reader :status, :error_code, :body, :headers
+
+    def initialize(message = nil, status: nil, error_code: nil, body: nil, headers: {})
+      @status = status
+      @error_code = error_code
+      @body = body
+      @headers = headers || {}
+      super(message || default_message)
+    end
+
+    # Builds the most specific error subclass for an HTTP status.
+    def self.for(status:, error_code: nil, message: nil, body: nil, headers: {})
+      klass = STATUS_CLASSES.fetch(status) do
+        status.to_i >= 500 ? ServerError : ApiError
+      end
+      klass.new(message, status: status, error_code: error_code, body: body, headers: headers)
+    end
+
+    def retryable?
+      RETRYABLE_STATUSES.include?(status)
+    end
+
+    # @example error.code?(Haskimail::ErrorCodes::TEMPLATE_NOT_FOUND)
+    def code?(code)
+      !error_code.nil? && error_code == code
+    end
+
+    private
+
+    def default_message
+      parts = []
+      parts << "HTTP #{status}" if status
+      parts << "ErrorCode #{error_code}" if error_code
+      parts.empty? ? "Haskimail API error" : "Haskimail API error (#{parts.join(', ')})"
+    end
+  end
+
+  # HTTP 401: the token is missing, wrong, or not valid for this method.
+  class UnauthorizedError < ApiError; end
+  # HTTP 403: the request IP is not on the account allowlist.
+  class ForbiddenError < ApiError; end
+  # HTTP 404: unknown method or ID.
+  class NotFoundError < ApiError; end
+  # HTTP 413: the batch is larger than 50 MB.
+  class PayloadTooLargeError < ApiError; end
+  # HTTP 422: validation error, see #error_code.
+  class UnprocessableEntityError < ApiError; end
+  # HTTP 429: too many requests.
+  class RateLimitError < ApiError; end
+  # HTTP 5xx.
+  class ServerError < ApiError; end
+  # HTTP 500.
+  class InternalServerError < ServerError; end
+  # HTTP 503: temporarily unavailable.
+  class ServiceUnavailableError < ServerError; end
+
+  class ApiError
+    STATUS_CLASSES = {
+      401 => UnauthorizedError,
+      403 => ForbiddenError,
+      404 => NotFoundError,
+      413 => PayloadTooLargeError,
+      422 => UnprocessableEntityError,
+      429 => RateLimitError,
+      500 => InternalServerError,
+      503 => ServiceUnavailableError
+    }.freeze
+  end
+
+  # Raised when a webhook payload fails signature or authentication checks.
+  class WebhookVerificationError < Error; end
+end

data/lib/haskimail/paginator.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Haskimail
+  # Lazily walks count/offset pages. Requests are made only while iterating.
+  #
+  #   client.messages.each_outbound(tag: "orders").first(1000)
+  #   client.bounces.each(type: "HardBounce").each { |bounce| ... }
+  class Paginator
+    include Enumerable
+
+    # @param items_key [Symbol] collection key in the (serialized) page response
+    # @param page_size [Integer]
+    # @param max_window [Integer, nil] API limit for count + offset
+    # @yieldparam count [Integer]
+    # @yieldparam offset [Integer]
+    # @yieldreturn [Hash] serialized page with :total_count and items_key
+    def initialize(items_key:, page_size:, max_window: nil, &fetch_page)
+      raise ArgumentError, "page_size must be a positive Integer" unless page_size.is_a?(Integer) && page_size.positive?
+
+      @items_key = items_key
+      @page_size = page_size
+      @max_window = max_window
+      @fetch_page = fetch_page
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block_given?
+
+      offset = 0
+      loop do
+        count = @page_size
+        count = [count, @max_window - offset].min if @max_window
+        break if count <= 0
+
+        page = @fetch_page.call(count, offset)
+        items = Array(page && page[@items_key])
+        items.each(&block)
+
+        offset += items.size
+        total = page && page[:total_count]
+        # Trust total_count when present (the server may cap the page size);
+        # otherwise a short page is the last one.
+        break if items.empty? || (total ? offset >= total : items.size < count)
+      end
+      self
+    end
+  end
+end

data/lib/haskimail/rails/delivery_method.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Haskimail
+  module Rails
+    # ActionMailer delivery method.
+    #
+    #   # config/environments/production.rb
+    #   config.action_mailer.delivery_method = :haskimail
+    #   config.action_mailer.haskimail_settings = {
+    #     api_token: Rails.application.credentials.dig(:haskimail, :server_token)
+    #   }
+    #
+    # Settings: :api_token (or :server_token), :return_response, and any
+    # Haskimail::Configuration option (:default_message_stream, :read_timeout, ...).
+    # Without a token the global Haskimail configuration is used.
+    class DeliveryMethod
+      TOKEN_KEYS = %i[api_token server_token].freeze
+
+      attr_accessor :settings
+
+      def initialize(settings = {})
+        @settings = (settings || {}).to_h.transform_keys(&:to_sym)
+      end
+
+      # @return [Mail::Message, Hash] the message, or the API response with return_response: true
+      def deliver!(mail)
+        payload = MailConverter.call(mail)
+        client = build_client
+        response = mail.haskimail.template? ? client.deliver_with_template(payload) : client.deliver(payload)
+        mail.haskimail.response = response
+        settings[:return_response] ? response : mail
+      end
+
+      def inspect
+        "#<#{self.class.name} settings=#{settings.except(*TOKEN_KEYS).inspect}>"
+      end
+
+      # Safe for logs and error trackers: tokens are redacted.
+      def as_json(*)
+        { "settings" => settings.to_h { |k, v| [k.to_s, TOKEN_KEYS.include?(k) ? Secret::REDACTED : v] } }
+      end
+
+      def to_json(*args)
+        as_json.to_json(*args)
+      end
+
+      private
+
+      def build_client
+        token = settings[:api_token] || settings[:server_token]
+        options = settings.except(*TOKEN_KEYS, :return_response)
+        ServerClient.new(token, **options)
+      end
+    end
+  end
+end

data/lib/haskimail/rails/mail_converter.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+
+module Haskimail
+  module Rails
+    # Converts a Mail::Message (as built by ActionMailer) into an API payload.
+    module MailConverter
+      # Headers mapped to dedicated API fields or managed by Haskimail itself.
+      # Message-ID is reserved too: ActionMailer generates one for every message
+      # and Haskimail assigns its own MessageID.
+      RESERVED_HEADERS = %w[
+        from to cc bcc reply-to subject date sender return-path received mime-version message-id
+        content-type content-transfer-encoding content-disposition content-id
+      ].freeze
+
+      # User data that is sent even when empty.
+      KEEP_WHEN_EMPTY = %w[TemplateModel].freeze
+
+      # SMTP-compatible headers (https://haskimail.ru/developer/user-guide/send-email-with-smtp),
+      # honoured here too so mailers work the same over SMTP and the HTTP API.
+      HM_TAG = "x-hm-tag"
+      HM_METADATA = "x-hm-metadata"
+      HM_TRACK_OPENS = "x-hm-trackopens"
+      HM_NO_TRACK_OPENS = "x-hm-no-track-opens"
+      HM_NO_TRACK_CLICK = "x-hm-no-track-click"
+      # Converted into API fields; other X-HM-* headers (X-HM-Domain,
+      # X-HM-MessageID) are passed through to Haskimail unchanged.
+      CONSUMED_HM_HEADERS = [HM_TAG, HM_METADATA, HM_TRACK_OPENS, HM_NO_TRACK_OPENS, HM_NO_TRACK_CLICK].freeze
+
+      module_function
+
+      # @param mail [Mail::Message]
+      # @return [Hash] API payload with String keys
+      def call(mail)
+        options = mail.respond_to?(:haskimail) ? mail.haskimail : MessageOptions.new
+        payload = {
+          "From" => address_list(mail, :from).first,
+          "To" => join(address_list(mail, :to)),
+          "Cc" => join(address_list(mail, :cc)),
+          "Bcc" => join(address_list(mail, :bcc)),
+          "ReplyTo" => join(address_list(mail, :reply_to)),
+          "Subject" => mail.subject,
+          "Headers" => custom_headers(mail),
+          "Attachments" => attachments(mail)
+        }
+        payload.merge!(bodies(mail)) unless options.template?
+        payload.merge!(header_options(mail))
+        payload.merge!(options.to_api)
+        payload.reject { |key, value| Util.blank?(value) && value != false && !KEEP_WHEN_EMPTY.include?(key) }
+      end
+
+      def address_list(mail, field)
+        header = mail[field]
+        return [] unless header
+
+        Array(header.respond_to?(:formatted) ? header.formatted : header.value).compact
+      end
+
+      def join(list)
+        list.empty? ? nil : list.join(", ")
+      end
+
+      def bodies(mail)
+        if mail.multipart?
+          { "HtmlBody" => decode(mail.html_part), "TextBody" => decode(mail.text_part) }
+        elsif mail.mime_type == "text/html"
+          { "HtmlBody" => decode(mail) }
+        else
+          { "TextBody" => decode(mail) }
+        end
+      end
+
+      def decode(part)
+        return nil unless part
+
+        part.decoded.to_s.dup.force_encoding(Encoding::UTF_8).scrub
+      end
+
+      def custom_headers(mail)
+        mail.header.fields.filter_map do |field|
+          name = field.name.to_s
+          key = name.downcase
+          next if RESERVED_HEADERS.include?(key) || CONSUMED_HM_HEADERS.include?(key)
+
+          { "Name" => name, "Value" => field.value.to_s }
+        end
+      end
+
+      def attachments(mail)
+        mail.attachments.map do |attachment|
+          Haskimail::Attachment.assert_allowed!(attachment.filename)
+          item = {
+            "Name" => attachment.filename,
+            "Content" => Base64.strict_encode64(attachment.decoded),
+            "ContentType" => attachment.mime_type
+          }
+          # Bare Content-ID: the HTML references it as "cid:<id>" (Rails' attachment.url).
+          item["ContentID"] = Haskimail::Attachment.normalize_content_id(attachment.content_id) if attachment.inline?
+          item
+        end
+      end
+
+      # Values from X-HM-* headers; explicit `message.haskimail` settings win.
+      def header_options(mail)
+        result = {}
+        result["Tag"] = header_value(mail, HM_TAG)
+        if (raw = header_value(mail, HM_METADATA))
+          metadata = JSON.parse(raw)
+          raise ArgumentError, "X-HM-Metadata must be a JSON object" unless metadata.is_a?(Hash)
+
+          result["Metadata"] = metadata
+        end
+        track_opens = header_value(mail, HM_TRACK_OPENS)
+        result["TrackOpens"] = track_opens.casecmp?("true") if track_opens
+        result["TrackOpens"] = false if header_value(mail, HM_NO_TRACK_OPENS)
+        result["TrackLinks"] = false if header_value(mail, HM_NO_TRACK_CLICK)
+        result.compact
+      rescue JSON::ParserError
+        raise ArgumentError, "X-HM-Metadata must be valid JSON"
+      end
+
+      def header_value(mail, name)
+        field = mail.header.fields.find { |candidate| candidate.name.to_s.casecmp?(name) }
+        field&.value&.to_s
+      end
+    end
+  end
+end

data/lib/haskimail/rails/mailer_helpers.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Haskimail
+  module Rails
+    # Helpers available in every ActionMailer::Base subclass.
+    #
+    #   class OrderMailer < ApplicationMailer
+    #     def created(order)
+    #       haskimail tag: "orders", metadata: { order_id: order.id }, message_stream: "2081"
+    #       mail to: order.email, subject: "Заказ №#{order.number} оформлен"
+    #     end
+    #
+    #     def welcome(user)
+    #       haskimail_template "welcome", model: { "{{name}}" => user.name }, to: user.email
+    #     end
+    #   end
+    module MailerHelpers
+      # Sets Haskimail options (tag, metadata, message_stream, track_opens,
+      # track_links, template, template_model) for the message being built.
+      def haskimail(**options)
+        message.haskimail.assign(options)
+      end
+
+      # Sends a Haskimail template instead of a rendered view. The subject comes
+      # from the template unless `subject:` is given.
+      # @param template [Integer, String] template ID or alias
+      # @param model [Hash] placeholders, e.g. { "{{name}}" => "Иван" }
+      # @param headers [Hash] regular ActionMailer headers (to:, from:, cc:, subject:, ...)
+      def haskimail_template(template, model: {}, **headers)
+        if (stray = headers.keys.grep_v(Symbol)).any?
+          raise ArgumentError, "Unexpected header(s) #{stray.inspect}: pass the template model as model: { ... }"
+        end
+
+        haskimail(template: template, template_model: model)
+        # A blank subject stops ActionMailer from adding its default i18n subject.
+        mail({ subject: "" }.merge(headers)) do |format|
+          format.text { render plain: "" }
+        end
+      end
+    end
+  end
+end