haskimail 1.0.0

data/lib/haskimail/resources/messages.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Haskimail
+  module Resources
+    # Shared logic for outbound searches limited to count + offset <= 10000.
+    # @api private
+    class OutboundSearch < Base
+      # Documented maximum of count.
+      MAX_PAGE_SIZE = 500
+      # Documented maximum of count + offset.
+      MAX_WINDOW = 10_000
+
+      private
+
+      def search(endpoint, filters, mapping)
+        check_paging!(filters[:count], filters[:offset], max_count: MAX_PAGE_SIZE, max_window: MAX_WINDOW)
+        api_get(endpoint, query(filters, mapping))
+      end
+
+      def iterate(endpoint, items_key, filters, mapping, page_size)
+        reject_paging!(filters)
+        check_page_size!(page_size, MAX_PAGE_SIZE)
+        base = query(filters, mapping)
+        paginate(items_key, page_size: page_size, max_window: MAX_WINDOW) do |count, offset|
+          api_get(endpoint, base.merge("count" => count, "offset" => offset))
+        end
+      end
+    end
+
+    # Sent messages: https://haskimail.ru/developer/api/messages-api
+    class Messages < OutboundSearch
+      # Keyword => query parameter.
+      FILTERS = PAGING.merge(
+        recipient: "recipient", from_email: "fromemail", tag: "tag", subject: "subject",
+        message_stream: "messagestream", from_date: "fromdate", to_date: "todate"
+      ).freeze
+
+      # GET /messages — newest first, one record per recipient.
+      # `from_date`/`to_date` accept Date, Time (converted to Moscow time) or String.
+      # @return [ApiObject] TotalCount, Messages[]
+      def list(**filters)
+        object(search("/messages", filters, FILTERS))
+      end
+
+      # Iterates over search results (the API caps the window at 10 000 records).
+      # @return [Paginator]
+      def each(page_size: MAX_PAGE_SIZE, **filters, &block)
+        run(iterate("/messages", "Messages", filters, FILTERS, page_size), block)
+      end
+
+      # GET /messages/{messageid}/details
+      # @raise [UnprocessableEntityError] ErrorCode 701 when not found
+      def details(message_id)
+        object(api_get(path("/messages/%s/details", message_id)))
+      end
+    end
+
+    # Open events: https://haskimail.ru/developer/api/messages-api
+    class Opens < OutboundSearch
+      # Keyword => query parameter.
+      FILTERS = PAGING.merge(
+        recipient: "recipient", tag: "tag", message_stream: "messagestream",
+        from_date: "fromdate", to_date: "todate"
+      ).freeze
+      # Filters of #for_message.
+      MESSAGE_FILTERS = PAGING.merge(recipient: "recipient", tag: "tag", message_stream: "messagestream").freeze
+
+      # GET /messages/opens
+      # @return [ApiObject] TotalCount, Opens[]
+      def list(**filters)
+        object(search("/messages/opens", filters, FILTERS))
+      end
+
+      # @return [Paginator]
+      def each(page_size: MAX_PAGE_SIZE, **filters, &block)
+        run(iterate("/messages/opens", "Opens", filters, FILTERS, page_size), block)
+      end
+
+      # GET /messages/opens/{messageid} — all opens of one email.
+      def for_message(message_id, **filters)
+        object(search(path("/messages/opens/%s", message_id), filters, MESSAGE_FILTERS))
+      end
+    end
+
+    # Link clicks: https://haskimail.ru/developer/api/messages-api
+    class Clicks < OutboundSearch
+      # Same filters as Opens.
+      FILTERS = Opens::FILTERS
+      # Same filters as Opens#for_message.
+      MESSAGE_FILTERS = Opens::MESSAGE_FILTERS
+
+      # GET /messages/clicks
+      # @return [ApiObject] TotalCount, Clicks[]
+      def list(**filters)
+        object(search("/messages/clicks", filters, FILTERS))
+      end
+
+      # @return [Paginator]
+      def each(page_size: MAX_PAGE_SIZE, **filters, &block)
+        run(iterate("/messages/clicks", "Clicks", filters, FILTERS, page_size), block)
+      end
+
+      # GET /messages/clicks/{messageid} — all clicks of one email.
+      def for_message(message_id, **filters)
+        object(search(path("/messages/clicks/%s", message_id), filters, MESSAGE_FILTERS))
+      end
+    end
+
+    # Inbound messages (server token only): https://haskimail.ru/developer/api/messages-api
+    class InboundMessages < Base
+      # Keyword => query parameter.
+      FILTERS = PAGING.merge(
+        recipient: "recipient", from_email: "fromemail", subject: "subject",
+        mailbox_hash: "mailboxhash", status: "status", from_date: "fromdate", to_date: "todate"
+      ).freeze
+      # Accepted values of the status filter.
+      STATUSES = %w[queued processed blocked failed scheduled].freeze
+      # Documented maximum of count.
+      MAX_PAGE_SIZE = 500
+
+      # GET /messages/inbound — last 45 days, newest first.
+      # @option filters [String, Symbol] :status one of STATUSES, any case
+      #   (the API itself reports statuses capitalized: "Blocked")
+      # @return [ApiObject] TotalCount, InboundMessages[]
+      def list(**filters)
+        object(api_get("/messages/inbound", build_query(filters)))
+      end
+
+      # @return [Paginator]
+      def each(page_size: MAX_PAGE_SIZE, **filters, &block)
+        reject_paging!(filters)
+        check_page_size!(page_size, MAX_PAGE_SIZE)
+        base = build_query(filters)
+        paginator = paginate("InboundMessages", page_size: page_size) do |count, offset|
+          api_get("/messages/inbound", base.merge("count" => count, "offset" => offset))
+        end
+        run(paginator, block)
+      end
+
+      # GET /messages/inbound/{messageid}/details
+      def details(message_id)
+        object(api_get(path("/messages/inbound/%s/details", message_id)))
+      end
+
+      # PUT /messages/inbound/{messageid}/bypass — delivers a Blocked message to the webhook.
+      def bypass(message_id)
+        object(api_put(path("/messages/inbound/%s/bypass", message_id), idempotent: false))
+      end
+
+      # PUT /messages/inbound/{messageid}/retry — re-delivers a Failed message.
+      def retry(message_id)
+        object(api_put(path("/messages/inbound/%s/retry", message_id), idempotent: false))
+      end
+
+      private
+
+      def build_query(filters)
+        check_paging!(filters[:count], filters[:offset], max_count: MAX_PAGE_SIZE)
+        unless filters[:status].nil?
+          wanted = filters[:status].to_s.b.downcase # ASCII-only, safe for any bytes
+          status = STATUSES.find { |name| name == wanted }
+          raise ValidationError, "status must be one of: #{STATUSES.join(', ')}" unless status
+
+          filters = filters.merge(status: status)
+        end
+
+        # This endpoint expects ISO-like "2026-09-01T12:00:00" timestamps.
+        prepared = filters.to_h do |key, value|
+          value = value.to_time if value.is_a?(DateTime)
+          [key, value.is_a?(Time) ? Util.format_time(value, separator: "T") : value]
+        end
+        query(prepared, FILTERS)
+      end
+    end
+  end
+end

data/lib/haskimail/resources/server_resources.rb

@@ -0,0 +1,297 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Haskimail
+  module Resources
+    # Bounces: https://haskimail.ru/developer/api/bounce-api
+    class Bounces < Base
+      # Keyword => query parameter.
+      FILTERS = PAGING.merge(
+        type: "type", email_filter: "emailFilter", tag: "tag", message_id: "messageID",
+        message_stream: "messagestream", from_date: "fromdate", to_date: "todate"
+      ).freeze
+
+      # Values accepted by the `type:` filter. The delivery-stats spellings
+      # (BulkBounce, SpamBlock) are accepted by the API as well.
+      TYPES = %w[HardBounce SoftBounce BlkBounce SpmBounce BulkBounce SpamBlock].freeze
+
+      # GET /deliverystats — bounce counts by type for the last 45 days.
+      # @return [ApiObject] Bounces[] (Type, Name, Count)
+      def delivery_stats
+        object(api_get("/deliverystats"))
+      end
+
+      # GET /bounces — newest first.
+      # @return [ApiObject] TotalCount, Bounces[]
+      def list(**filters)
+        object(api_get("/bounces", build_query(filters)))
+      end
+
+      # @return [Paginator]
+      def each(page_size: 500, **filters, &block)
+        reject_paging!(filters)
+        base = build_query(filters)
+        paginator = paginate("Bounces", page_size: page_size) do |count, offset|
+          api_get("/bounces", base.merge("count" => count, "offset" => offset))
+        end
+        run(paginator, block)
+      end
+
+      private
+
+      def build_query(filters)
+        check_paging!(filters[:count], filters[:offset])
+        type = filters[:type]
+        raise ValidationError, "type must be one of: #{TYPES.join(', ')}" if type && !TYPES.include?(type.to_s)
+
+        query(Dates.date_only(filters), FILTERS)
+      end
+    end
+
+    # Converts date filters for endpoints that accept only dates.
+    # @api private
+    module Dates
+      # Filters converted to YYYY-MM-DD.
+      KEYS = %i[from_date to_date].freeze
+
+      # Converts from_date/to_date for endpoints that accept only YYYY-MM-DD.
+      def self.date_only(filters)
+        filters.to_h { |key, value| KEYS.include?(key) ? [key, Util.format_date(value)] : [key, value] }
+      end
+    end
+
+    # Message streams: https://haskimail.ru/developer/api/message-streams-api
+    class MessageStreams < Base
+      # Accepted message_stream_type values.
+      TYPES = %w[transactional broadcasts].freeze
+
+      # GET /message-streams (archived streams included)
+      # @return [ApiObject] TotalCount, MessageStreams[]
+      def list
+        object(api_get("/message-streams"))
+      end
+
+      # GET /message-streams/{streamid}
+      def get(stream_id)
+        object(api_get(path("/message-streams/%s", stream_id)))
+      end
+
+      # POST /message-streams
+      # @param message_stream_type [String, Symbol] "transactional" or "broadcasts"
+      # @param server_id [Integer, nil] required with the account token
+      def create(name:, message_stream_type:, server_id: nil)
+        if server_id.nil? && @client.is_a?(AccountClient)
+          raise ValidationError, "server_id is required with the account token"
+        end
+
+        unless TYPES.include?(Util.strip_text(message_stream_type, "message_stream_type").downcase)
+          raise ValidationError, "message_stream_type must be transactional or broadcasts"
+        end
+
+        payload = Util.to_api(name: name, message_stream_type: message_stream_type.to_s, server_id: server_id)
+        object(api_post("/message-streams", payload))
+      end
+
+      # PATCH /message-streams/{streamid} — only the name can be changed.
+      def update(stream_id, name:)
+        raise ValidationError, "name must not be blank" if Util.blank?(name)
+
+        object(api_patch(path("/message-streams/%s", stream_id), { "Name" => name }))
+      end
+
+      # POST /message-streams/{streamid}/archive — deleted after 45 days unless unarchived.
+      def archive(stream_id)
+        object(api_post(path("/message-streams/%s/archive", stream_id), idempotent: true))
+      end
+
+      # POST /message-streams/{streamid}/unarchive
+      def unarchive(stream_id)
+        object(api_post(path("/message-streams/%s/unarchive", stream_id), idempotent: true))
+      end
+    end
+
+    # Suppression lists: https://haskimail.ru/developer/api/suppressions-api
+    class Suppressions < Base
+      # GET /message-streams/{streamid}/suppressions/dump
+      # @return [ApiObject] Suppressions[] (EmailAddress, SuppressionReason, Origin, CreatedAt)
+      def list(stream_id)
+        object(api_get(path("/message-streams/%s/suppressions/dump", stream_id)))
+      end
+
+      # POST /message-streams/{streamid}/suppressions
+      # @param emails [Array<String>, String]
+      # @return [ApiObject] per-address Status: Suppressed / Failed
+      def create(stream_id, emails)
+        object(api_post(path("/message-streams/%s/suppressions", stream_id), payload(emails), idempotent: true))
+      end
+
+      # POST /message-streams/{streamid}/suppressions/delete
+      # @return [ApiObject] per-address Status: Deleted / Failed
+      def delete(stream_id, emails)
+        object(api_post(path("/message-streams/%s/suppressions/delete", stream_id), payload(emails),
+                        idempotent: true))
+      end
+
+      private
+
+      def payload(emails)
+        list = Array(emails).map { |email| Util.strip_text(email, "Email address") }
+        raise ValidationError, "At least one email address is required" if list.empty?
+        raise ValidationError, "Email addresses must not be blank" if list.any?(&:empty?)
+
+        { "Suppressions" => list.map { |email| { "EmailAddress" => email } } }
+      end
+    end
+
+    # Webhooks: https://haskimail.ru/developer/api/webhooks-api
+    class Webhooks < Base
+      # Keyword => API trigger name.
+      TRIGGERS = {
+        delivery: "Delivery", bounce: "Bounce", spam_complaint: "SpamComplaint",
+        open: "Open", click: "Click", subscription_change: "SubscriptionChange"
+      }.freeze
+
+      # GET /webhooks
+      # @return [ApiObject] Webhooks[]
+      def list
+        object(api_get("/webhooks"))
+      end
+
+      # GET /webhooks/{webhookid}
+      def get(webhook_id)
+        object(api_get(path("/webhooks/%s", webhook_id)))
+      end
+
+      # POST /webhooks
+      #
+      #   client.webhooks.create(url: "https://example.com/haski",
+      #                          message_stream: "2081",
+      #                          triggers: { delivery: true, bounce: true, spam_complaint: true })
+      #
+      # Triggers not listed are disabled. The long API form
+      # (`{ "Bounce" => { "Enabled" => true } }`) is accepted too.
+      def create(url:, message_stream: nil, triggers: {})
+        payload = { "Url" => check_url!(url), "Triggers" => normalize_triggers(triggers) }
+        payload["MessageStream"] = message_stream.to_s unless message_stream.nil?
+        object(api_post("/webhooks", payload))
+      end
+
+      # PUT /webhooks/{webhookid} — only given triggers change; the stream cannot change.
+      def update(webhook_id, url: nil, triggers: nil)
+        payload = {}
+        payload["Url"] = check_url!(url) unless url.nil?
+        payload["Triggers"] = normalize_triggers(triggers) unless triggers.nil? || triggers == {}
+        raise ValidationError, "Nothing to update: pass url: and/or triggers:" if payload.empty?
+
+        object(api_put(path("/webhooks/%s", webhook_id), payload))
+      end
+
+      # DELETE /webhooks/{webhookid}
+      def delete(webhook_id)
+        object(api_delete(path("/webhooks/%s", webhook_id)))
+      end
+
+      private
+
+      def check_url!(url)
+        uri = URI.parse(url.to_s)
+        valid = %w[http https].include?(uri.scheme) && !uri.host.to_s.empty?
+        raise ValidationError, "Webhook url must be an http(s) URL" unless valid
+
+        url.to_s
+      rescue URI::InvalidURIError
+        raise ValidationError, "Webhook url is not a valid URL"
+      end
+
+      def normalize_triggers(triggers)
+        raise ValidationError, "triggers must be a Hash" unless triggers.is_a?(Hash)
+
+        triggers.each_with_object({}) do |(name, value), result|
+          api_name = name.is_a?(Symbol) ? TRIGGERS[name] : name.to_s
+          if api_name.nil? || !TRIGGERS.value?(api_name)
+            raise ValidationError, "Unknown trigger #{name.inspect}. Allowed: #{TRIGGERS.keys.join(', ')}"
+          end
+
+          result[api_name] = { "Enabled" => enabled_flag(name, value) }
+        end
+      end
+
+      def enabled_flag(name, value)
+        if value.is_a?(Hash)
+          key = ["Enabled", :enabled, :Enabled, "enabled"].find { |candidate| value.key?(candidate) }
+          value = key.nil? ? nil : value[key]
+        end
+        return value if [true, false].include?(value)
+
+        raise ValidationError, "Trigger #{name.inspect} must be true or false"
+      end
+    end
+
+    # Inbound blocking rules (server token): https://haskimail.ru/developer/api/inbound-rules-triggers-api
+    class InboundRules < Base
+      # Documented maximum of count.
+      MAX_PAGE_SIZE = 500
+
+      # GET /triggers/inboundrules
+      # @return [ApiObject] TotalCount, InboundRules[] (ID, Rule)
+      def list(count: nil, offset: nil)
+        check_paging!(count, offset, max_count: MAX_PAGE_SIZE)
+        object(api_get("/triggers/inboundrules", query({ count: count, offset: offset }, PAGING)))
+      end
+
+      # @return [Paginator]
+      def each(page_size: MAX_PAGE_SIZE, &block)
+        check_page_size!(page_size, MAX_PAGE_SIZE)
+        paginator = paginate("InboundRules", page_size: page_size) do |count, offset|
+          api_get("/triggers/inboundrules", { "count" => count, "offset" => offset })
+        end
+        run(paginator, block)
+      end
+
+      # POST /triggers/inboundrules
+      # @param rule [String] email address ("spam@example.com") or whole domain ("example.org")
+      def create(rule)
+        text = Util.strip_text(rule, "Rule")
+        raise ValidationError, "rule must not be blank" if text.empty?
+
+        object(api_post("/triggers/inboundrules", { "Rule" => text }))
+      end
+
+      # DELETE /triggers/inboundrules/{triggerid}
+      def delete(rule_id)
+        object(api_delete(path("/triggers/inboundrules/%s", rule_id)))
+      end
+    end
+
+    # Outbound 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
+      # Keyword => query parameter.
+      FILTERS = { from_date: "fromdate", to_date: "todate", message_stream: "messagestream" }.freeze
+
+      # Method name => endpoint.
+      ENDPOINTS = {
+        summary: "/stats",
+        sends: "/stats/sends",
+        bounces: "/stats/bounces",
+        spam_complaints: "/stats/spam",
+        opens: "/stats/opens",
+        clicks: "/stats/clicks",
+        opens_by_platform: "/stats/opens/platforms",
+        opens_by_email_client: "/stats/opens/emailclients",
+        clicks_by_browser_family: "/stats/clicks/browserfamilies",
+        clicks_by_platform: "/stats/clicks/platforms"
+      }.freeze
+
+      ENDPOINTS.each do |name, endpoint|
+        define_method(name) do |**filters|
+          # @type self: Stats
+          object(api_get(endpoint, query(Dates.date_only(filters), FILTERS)))
+        end
+      end
+    end
+  end
+end

data/lib/haskimail/resources/templates.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Haskimail
+  module Resources
+    # Templates: https://haskimail.ru/developer/api/templates-api
+    # Sending by template lives in {Emails#deliver_with_template}.
+    class Templates < Base
+      # GET /templates
+      # @return [ApiObject] TotalCount, Templates[]
+      def list(count: nil, offset: nil)
+        check_paging!(count, offset)
+        object(api_get("/templates", query({ count: count, offset: offset }, PAGING)))
+      end
+
+      # Iterates over all templates, requesting pages lazily.
+      # @return [Paginator]
+      def each(page_size: 500, &block)
+        paginator = paginate("Templates", page_size: page_size) do |count, offset|
+          api_get("/templates", { "count" => count, "offset" => offset })
+        end
+        run(paginator, block)
+      end
+
+      # GET /templates/{templateIdOrAlias}
+      # @param id_or_alias [Integer, String]
+      def get(id_or_alias)
+        object(api_get(path("/templates/%s", id_or_alias)))
+      end
+
+      # POST /templates
+      #   client.templates.create(name: "order-created", subject: "Заказ {{order}}",
+      #                           html_body: "<p>{{name}}</p>", text_body: "{{name}}")
+      def create(params = nil, **fields)
+        payload = Util.to_api(merge_params(params, fields))
+        raise ValidationError, "name is required" if Util.blank?(payload["Name"])
+
+        object(api_post("/templates", payload))
+      end
+
+      # PUT /templates/{templateIdOrAlias}
+      #
+      # The API overwrites all four fields and blanks any that are omitted,
+      # so all four are required here to prevent accidental data loss.
+      # Pass "" explicitly to clear a field.
+      def update(id_or_alias, name:, subject:, html_body:, text_body:)
+        payload = { "Name" => name, "Subject" => subject, "HtmlBody" => html_body, "TextBody" => text_body }
+        payload.each do |field, value|
+          raise ValidationError, "#{field} must be a String (use \"\" to clear it)" unless value.is_a?(String)
+        end
+        raise ValidationError, "name must not be blank" if Util.blank?(name)
+
+        object(api_put(path("/templates/%s", id_or_alias), payload))
+      end
+
+      # DELETE /templates/{templateIdOrAlias}
+      def delete(id_or_alias)
+        object(api_delete(path("/templates/%s", id_or_alias)))
+      end
+
+      # POST /templates/validate — renders a template without saving or sending.
+      # Answers 200 even if the template has errors: check `all_content_is_valid`.
+      #
+      #   result = client.templates.validate(subject: "Заказ {{order}}",
+      #                                      test_render_model: { "{{order}}" => "1042" })
+      #   result.all_content_is_valid # => true
+      def validate(params = nil, **fields)
+        payload = Util.to_api(merge_params(params, fields))
+        unless %w[Subject HtmlBody TextBody].any? { |key| payload.key?(key) }
+          raise ValidationError, "At least one of subject, html_body, text_body is required"
+        end
+
+        object(api_post("/templates/validate", payload, idempotent: true))
+      end
+    end
+
+    # Templates as seen by the account token; adds moving between servers.
+    class AccountTemplates < Templates
+      # POST /templates — with the account token `associated_server_id:` is
+      # required (the server the template is created on).
+      def create(params = nil, **fields)
+        merged = merge_params(params, fields)
+        unless Util.to_api(merged).key?("AssociatedServerId")
+          raise ValidationError, "associated_server_id is required with the account token"
+        end
+
+        super(merged)
+      end
+
+      # PUT /templates/push — MOVES (not copies) every template of one server
+      # to another. Use `perform_changes: false` for a dry run.
+      #
+      # @param perform_changes [Boolean] required on purpose: no default for a destructive call
+      def push(source_server_id:, destination_server_id:, perform_changes:)
+        raise ValidationError, "perform_changes must be true or false" unless [true, false].include?(perform_changes)
+
+        payload = {
+          "SourceServerID" => source_server_id,
+          "DestinationServerID" => destination_server_id,
+          "PerformChanges" => perform_changes
+        }
+        object(api_put("/templates/push", payload, idempotent: false))
+      end
+    end
+  end
+end

data/lib/haskimail/test_addresses.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Haskimail
+  # Addresses that simulate bounces and spam complaints. The email goes nowhere
+  # and Haskimail creates the event immediately — as for a real bounce — so you
+  # can test bounce handling and webhooks. They work on live and sandbox
+  # servers, do not use the email quota, but do NOT work with {TEST_TOKEN}.
+  # https://haskimail.ru/developer/user-guide/sandbox-mode/generate-fake-bounces
+  #
+  #   client.emails.deliver(from: "shop@example.com", to: Haskimail::TestAddresses::HARD_BOUNCE,
+  #                         subject: "Проверка", text_body: "Тест")
+  module TestAddresses
+    # Domain of the test addresses.
+    DOMAIN = "bounce-testing.haskimail.ru"
+
+    # Hard bounce, SMTP code 550 (the recipient does not exist).
+    HARD_BOUNCE = "hardbounce@#{DOMAIN}".freeze
+    # Soft bounce, SMTP code 450 (the mailbox is temporarily unavailable).
+    SOFT_BOUNCE = "softbounce@#{DOMAIN}".freeze
+    # Blocked by the recipient's mail server, SMTP code 554.
+    BLOCKED = "blocked@#{DOMAIN}".freeze
+    # Spam complaint.
+    SPAM_COMPLAINT = "spamnotification@#{DOMAIN}".freeze
+  end
+end