haskimail-rails 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: adf6acf3fcc25870152c555a7446a4de75c110db5f8afc1066ef529652791214
+  data.tar.gz: cb71e39592945d3dbcfc529c294a5c5da93a695b852f44fc66316e14cf9d4c9d
+SHA512:
+  metadata.gz: c2ed34f23437d20f3ac005b434213e4d83ce4b3dd1d1aa0b566e834ad8f95f43eb8d080368c127474441955154ccb9893148aa5494af74e97080a40175881cea
+  data.tar.gz: 3ca5ebbae9e138e1689db9c937597ed027793abcd1a0371522879d35cea8d5b2ad4620c74d5d30bf8fa555e2d958359ab0d6d46c0f670db6be9e69ea2289e0fd

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 1.0.0 — 2026-11-12
+
+Первый публичный релиз.
+
+- `Haskimail::AccountClient#servers.issue_token(server_id, name:)` — выпуск дополнительного серверного API-ключа (`POST /servers/{id}/tokens/new`).
+- ActionMailer delivery method `:haskimail` (теги, метаданные, каналы, трекинг, вложения, inline-картинки, шаблоны Haskimail, SMTP-заголовки `X-HM-*`).
+- `Haskimail::ServerClient`: письма, пакеты, шаблоны, сообщения, открытия, клики, входящие, возвраты, каналы, статистика, вебхуки, правила для входящих, стоп-листы.
+- `Haskimail::AccountClient`: серверы, домены, перенос шаблонов.
+- Ретраи без дублей писем, keep-alive соединения, безопасные для потоков и `fork`, инструментирование через ActiveSupport::Notifications.
+- `Haskimail::Webhooks`: разбор событий и входящих писем, проверка подписи и Basic auth, Rack-эндпоинт.
+- Генератор `rails g haskimail:install`.
+- Поддержка Ruby 3.1+ и Rails 6.1–8.x.
+- Из `Servers::UPDATABLE` убрано `enable_smtp_api_error_hooks` — поле отсутствует в API и игнорировалось.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DashaMail
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,267 @@
+# haskimail-rails
+
+Ruby on Rails SDK для [Haskimail](https://haskimail.ru), сервиса транзакционных писем.
+
+* Метод доставки ActionMailer `:haskimail` с тегами, метаданными, каналами, трекингом, вложениями и inline-картинками.
+* Полное покрытие HTTP API: письма, шаблоны, сообщения, возвраты, каналы, статистика, вебхуки, правила для входящих, стоп-листы, серверы и домены.
+* Безопасные ретраи с экспоненциальной задержкой и jitter: письмо **никогда** не отправится дважды.
+* Приём вебхуков: Rack-эндпоинт с Basic auth и проверкой подписи в постоянное время, типизированные события.
+* Из зависимостей только ActionMailer и `base64`. Keep-alive соединения, безопасные для потоков и `fork`. TLS 1.2+.
+* Токены не попадают в логи, `inspect`, `to_json` и трекеры ошибок.
+
+Требования: Ruby 3.1+, Rails / ActionMailer 6.1+.
+
+## Установка
+
+```ruby
+# Gemfile
+gem "haskimail-rails"
+```
+
+```sh
+bundle install
+bin/rails generate haskimail:install   # создаст config/initializers/haskimail.rb
+bin/rails credentials:edit
+```
+
+```yaml
+haskimail:
+  server_token: "серверный API-ключ"
+  account_token: "API-ключ аккаунта"   # нужен только для серверов, доменов и переноса шаблонов
+  webhook_key: "ключ подписи вебхуков"
+  webhook_password: "пароль для Basic auth вебхуков"
+```
+
+## ActionMailer
+
+```ruby
+# config/environments/production.rb
+config.action_mailer.delivery_method = :haskimail
+# Токен берётся из Haskimail.config. Можно задать явно:
+# config.action_mailer.haskimail_settings = { api_token: Rails.application.credentials.dig(:haskimail, :server_token) }
+```
+
+```ruby
+class OrderMailer < ApplicationMailer
+  default from: "Магазин <shop@example.com>"
+
+  def created(order)
+    haskimail tag: "orders",
+              metadata: { order_id: order.id.to_s },
+              message_stream: "2081",
+              track_opens: true,
+              track_links: true
+
+    attachments["invoice.pdf"] = order.invoice_pdf
+    attachments.inline["logo.png"] = File.binread("app/assets/images/logo.png")
+    # во вьюхе: image_tag attachments["logo.png"].url
+
+    mail to: order.email, subject: "Заказ №#{order.number} оформлен"
+  end
+
+  # Шаблон, который хранится в Haskimail
+  def welcome(user)
+    haskimail_template "welcome", model: { "{{name}}" => user.name }, to: user.email
+  end
+end
+```
+
+`track_opens` и `track_links` для письма принимают `true`/`false`; без них действует настройка сервера. На уровне сервера `TrackLinks` задаётся строкой (`None`, `HtmlAndText`, `HtmlOnly`, `TextOnly`) через `account.servers.update(id, track_links: "None")`; `true` и `false` там тоже принимаются.
+
+После отправки ответ API доступен в `message.haskimail.response`, ID письма в `message.haskimail.message_id`.
+
+Поддерживаются и SMTP-заголовки Haskimail (`X-HM-Tag`, `X-HM-Metadata`, `X-HM-TrackOpens`, `X-HM-No-Track-Opens`, `X-HM-No-Track-Click`), поэтому один и тот же мейлер работает и через SMTP, и через API. Явные настройки `haskimail(...)` важнее заголовков. Остальные заголовки, включая `X-HM-Domain` и `X-HM-MessageID`, передаются в Haskimail как есть.
+
+В development и test удобен тестовый токен: API проверяет запрос, но ничего не отправляет.
+
+```ruby
+Haskimail.config.server_token = Haskimail::TEST_TOKEN if Rails.env.development? || Rails.env.test?
+```
+
+## HTTP API
+
+```ruby
+client = Haskimail::ServerClient.new            # токен из Haskimail.config / ENV["HASKIMAIL_SERVER_TOKEN"]
+
+client.deliver(
+  from: "Магазин <shop@example.com>",
+  to: "ivan@example.com",
+  subject: "Ваш заказ №1042 оформлен",
+  html_body: "<p>Здравствуйте!</p>",
+  text_body: "Здравствуйте!",
+  tag: "orders",
+  metadata: { order_id: "1042" },
+  headers: { "X-Order-Id" => "1042" },
+  attachments: [Haskimail::Attachment.from_file("invoice.pdf")],
+  message_stream: "2081"
+)
+# => { to: "ivan@example.com", submitted_at: "2026-10-07 14:30:12", message_id: "6f1c…", error_code: 0, message: "OK" }
+```
+
+Ключи можно передавать в Ruby-стиле (`html_body:` или `"html_body"`, подходят и `params`) или ровно как в API (`"HtmlBody"`). Если одно поле задано дважды, SDK выдаст ошибку, а не выберет одно молча. Получателей можно передать строкой через запятую или массивом. Ответы приходят как Hash с ключами-символами в snake_case. Пользовательские данные (`Metadata`, `TemplateModel`, `TestRenderModel`) передаются как есть, без преобразования ключей.
+
+Вложения проще всего передавать через `Haskimail::Attachment`: он сам кодирует содержимое в Base64. В Hash-вложениях `content` уже должен быть в Base64. Для картинки внутри письма укажите `content_id: "logo.png"` и сошлитесь на неё в HTML как `<img src="cid:logo.png">`. Haskimail использует `ContentID` как Content-ID без изменений, поэтому SDK убирает префикс `cid:` и угловые скобки.
+
+### Пакетная отправка
+
+```ruby
+results = client.deliver_batch(messages)              # до 500 писем
+failed  = results.reject { |r| r[:error_code].zero? } # API отвечает 200, даже если часть писем отклонена
+
+client.deliver_with_template(template_alias: "order-created",
+                             template_model: { "{{name}}" => "Иван" },
+                             from: "shop@example.com", to: "ivan@example.com")
+client.deliver_batch_with_templates([...])
+```
+
+### Ресурсы сервера (`ServerClient`)
+
+| Ресурс | Методы |
+|---|---|
+| `emails` | `deliver`, `deliver_batch`, `deliver_with_template`, `deliver_batch_with_templates` |
+| `templates` | `get`, `list`, `each`, `create`, `update`, `patch`, `delete`, `validate` |
+| `messages` | `outbound`, `each_outbound`, `outbound_details`, `opens`, `each_open`, `opens_for`, `clicks`, `each_click`, `clicks_for`, `inbound`, `each_inbound`, `inbound_details`, `bypass_inbound`, `retry_inbound` |
+| `bounces` | `delivery_stats`, `list`, `each` |
+| `message_streams` | `list`, `get`, `create`, `update`, `archive`, `unarchive` |
+| `stats` | `overview`, `sends`, `bounces`, `spam_complaints`, `opens`, `clicks`, `open_platforms`, `click_platforms`, `email_clients`, `browser_families` |
+| `webhooks` | `list`, `get`, `create`, `update`, `delete` |
+| `inbound_rules` | `list`, `each`, `create`, `delete` |
+| `suppressions` | `list` (`dump`), `create` (`suppress`), `delete` (`unsuppress`) |
+
+### Ресурсы аккаунта (`AccountClient`)
+
+| Ресурс | Методы |
+|---|---|
+| `servers` | `get`, `list`, `each`, `create`, `update`, `delete` |
+| `domains` | `list`, `each`, `get`, `create`, `delete`, `verify_dkim`, `verify_spf` |
+| `templates` | `list`, `each` (шаблоны всех серверов), `validate`, `create`, `push` (перенос шаблонов между серверами) |
+
+```ruby
+account = Haskimail::AccountClient.new
+account.templates.push(source_server_id: 1, destination_server_id: 2, perform_changes: false) # сначала предпросмотр
+```
+
+### Фильтры, даты и пагинация
+
+```ruby
+client.messages.outbound(tag: "orders", recipient: "ivan@example.com",
+                         from_date: 1.week.ago, to_date: Date.current, count: 100)
+
+# Ленивый обход всех страниц (с учётом лимита API count + offset ≤ 10 000)
+client.bounces.each(type: "HardBounce").each { |bounce| ... }
+client.messages.each_outbound(tag: "orders").first(1_000)
+```
+
+`Date`, `Time` и `ActiveSupport::TimeWithZone` переводятся в московское время, как требует API. Неизвестные фильтры, ошибки в датах и нарушения лимитов API ловятся ещё до запроса с понятным `ArgumentError`.
+
+### Шаблоны
+
+`templates.update` перезаписывает шаблон целиком (так работает API), поэтому все четыре поля обязательны. Чтобы поменять одно поле, есть `templates.patch(id, subject: "…")`: он читает шаблон и сохраняет остальные поля.
+
+## Ошибки
+
+```
+Haskimail::Error
+├── ConfigurationError
+├── ConnectionError
+│   └── TimeoutError
+├── InvalidResponseError
+├── WebhookVerificationError
+└── ApiError                    # #status, #error_code, #body, #headers, #code?
+    ├── UnauthorizedError       # 401
+    ├── ForbiddenError          # 403, IP не в списке разрешённых
+    ├── NotFoundError           # 404
+    ├── PayloadTooLargeError    # 413, пакет больше 50 МБ
+    ├── UnprocessableEntityError# 422
+    ├── RateLimitError          # 429
+    └── ServerError             # 5xx
+        ├── InternalServerError       # 500
+        └── ServiceUnavailableError   # 503
+```
+
+```ruby
+begin
+  client.deliver_with_template(...)
+rescue Haskimail::UnprocessableEntityError => e
+  raise unless e.code?(Haskimail::ErrorCodes::TEMPLATE_NOT_FOUND)
+end
+```
+
+## Ретраи и надёжность
+
+| Ситуация | GET, PUT | POST (отправка), DELETE |
+|---|---|---|
+| Соединение не открылось (DNS, refused, open timeout) | повтор | повтор: запрос точно не ушёл |
+| Таймаут чтения, обрыв, 5xx, 429 | повтор | **без повтора**: запрос мог быть обработан |
+
+По умолчанию 2 повтора, экспоненциальная задержка с jitter, `Retry-After` учитывается (не дольше `retry_max_delay`). `PUT /messages/inbound/{id}/retry|bypass` не повторяются: повтор отправил бы письмо на ваш вебхук ещё раз.
+
+```ruby
+Haskimail.configure do |c|
+  c.open_timeout = 5
+  c.read_timeout = 30
+  c.max_retries = 2
+  c.default_message_stream = "2081"
+  c.logger = Rails.logger          # логируются только метод, путь, статус и время
+end
+```
+
+Каждый запрос публикуется в `ActiveSupport::Notifications` как `request.haskimail` с полями `method`, `path`, `attempt` и `status`, без токенов и персональных данных.
+
+Keep-alive соединения хранятся отдельно для каждого потока и файбера и не переиспользуются после `fork` (Puma, Unicorn). Для серверов с файбером на запрос (Falcon) поставьте `persistent_connections = false`.
+
+## Вебхуки
+
+```ruby
+# config/routes.rb
+mount Haskimail::Webhooks::Endpoint.new(
+  username: "haskimail",
+  password: Rails.application.credentials.dig(:haskimail, :webhook_password),
+  signature_key: Rails.application.credentials.dig(:haskimail, :webhook_key)
+) { |event| HaskimailWebhook.create!(payload: event.to_h).enqueue_processing }, at: "/haskimail/webhooks"
+```
+
+Входящее письмо с вложениями может весить около 14 МБ, поэтому лучше сначала сохранить его в базу или хранилище, а в очередь передать только ID записи.
+
+В Haskimail укажите URL `https://haskimail:ПАРОЛЬ@example.com/haskimail/webhooks`.
+
+```ruby
+class HaskimailWebhookJob < ApplicationJob
+  def perform(webhook_id)
+    event = Haskimail::Webhooks.parse(HaskimailWebhook.find(webhook_id).payload)
+    case event
+    when Haskimail::Webhooks::InboundMessage
+      Ticket.reply!(event.mailbox_hash, event.stripped_text_reply, event.attachments)
+    else
+      return if WebhookEvent.exists?(key: event.idempotency_key) # Haskimail может прислать событие повторно
+      User.find_by(email: event.recipient)&.disable_email! if event.hard_bounce? || event.complained?
+    end
+  end
+end
+```
+
+Безопасность эндпоинта:
+
+* Basic auth обязателен: без него эндпоинт не запустится. Принимать события только по подписи можно с явным `allow_signature_only: true`, входящие письма тогда отклоняются. Для локальной разработки есть `allow_unauthenticated: true`. Заданный `signature_key` проверяется всегда.
+* Basic auth проверяется до чтения тела запроса. Сравнение идёт в постоянное время.
+* Событие с ключом подписи принимается, только если поле `secret` совпадает с `MD5(recipient + message_id + ключ)`.
+* Входящие письма Haskimail не подписывает, поэтому они принимаются только при включённом Basic auth.
+* Подпись Haskimail покрывает только `recipient` и `message_id`: перехваченный `secret` можно переиспользовать с другим типом события. Поэтому рекомендуем Basic auth вместе с подписью и HTTPS.
+* Ответы: 200 — обработано, 401 — неверный логин или пароль, 403 — неверная подпись, 500 — упал ваш обработчик. Haskimail повторяет 5xx для всех вебхуков. Для входящих писем он повторяет и другие ответы, кроме 2xx и 403.
+
+Все события также публикуются в `ActiveSupport::Notifications` как `webhook.haskimail` с полями `{ type:, event: }`.
+
+Методы событий: `type` (`:delivered`, `:bounced`, `:complained`, `:opened`, `:clicked`, `:subscription_change`), предикаты (`bounced?`, `hard_bounce?`, …), `recipient`, `message_id`, `tag`, `metadata` (уже распарсенный Hash), `occurred_at` (UTC), `bounce_code`, `bounce_description`, `clicked_url`, `suppress_sending?`, `idempotency_key`.
+
+Если обрабатываете вебхуки в своём контроллере, используйте `Haskimail::Webhooks.parse(request.raw_post)`, `Haskimail::Webhooks.verify_signature!(event, key:)` и `Haskimail::Webhooks.valid_basic_auth?(request.authorization, username:, password:)`.
+
+## Разработка
+
+```sh
+bundle install
+bundle exec rake        # RSpec (покрытие ≥ 98% строк) + RuboCop
+```
+
+## Лицензия
+
+MIT

data/lib/generators/haskimail/install/install_generator.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Haskimail
+  module Generators
+    # rails generate haskimail:install
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+      desc "Creates config/initializers/haskimail.rb"
+
+      def copy_initializer
+        template "haskimail.rb", "config/initializers/haskimail.rb"
+      end
+
+      def show_next_steps
+        say <<~TEXT
+
+          Haskimail is installed. Next steps:
+            1. bin/rails credentials:edit  and add:
+                 haskimail:
+                   server_token: "..."
+                   account_token: "..."     # optional, for servers/domains
+                   webhook_password: "..."  # optional, Basic auth for webhooks
+                   webhook_key: "..."       # optional, webhook signature key
+            2. config/environments/production.rb:
+                 config.action_mailer.delivery_method = :haskimail
+        TEXT
+      end
+    end
+  end
+end

data/lib/generators/haskimail/install/templates/haskimail.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Haskimail: https://haskimail.ru/developer
+#
+# Tokens are read from HASKIMAIL_SERVER_TOKEN / HASKIMAIL_ACCOUNT_TOKEN by default;
+# values from credentials take precedence when present.
+Haskimail.configure do |config|
+  credentials = Rails.application.credentials.haskimail || {}
+
+  config.server_token = credentials[:server_token] if credentials[:server_token]
+  config.account_token = credentials[:account_token] if credentials[:account_token]
+
+  # Stream used when a message does not set one explicitly.
+  # config.default_message_stream = "2081"
+
+  # Network settings (seconds). Only requests that are safe to repeat are
+  # retried, so an email is never sent twice.
+  # config.open_timeout = 5
+  # config.read_timeout = 30
+  # config.max_retries = 2
+
+  # config.logger = Rails.logger
+end
+
+# Send-only test token for development and test: the API validates requests
+# but delivers nothing.
+# Haskimail.config.server_token = Haskimail::TEST_TOKEN if Rails.env.development? || Rails.env.test?

data/lib/haskimail/attachment.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module Haskimail
+  # An email attachment in the API format.
+  #
+  #   Haskimail::Attachment.from_file("invoice.pdf")
+  #   # Inline image, referenced in HTML as <img src="cid:logo.png">
+  #   Haskimail::Attachment.new(name: "logo.png", content: png_bytes, content_type: "image/png",
+  #                             content_id: "logo.png")
+  #
+  # The Content-ID is sent bare: Haskimail uses ContentID verbatim as the MIME
+  # Content-ID, so "cid:" prefixes and angle brackets are stripped.
+  class Attachment
+    # Extensions rejected by Haskimail (https://haskimail.ru/developer/user-guide/send-email-with-api).
+    FORBIDDEN_EXTENSIONS = %w[
+      vbs exe bin bat chm com cpl crt hlp hta inf ins isp jse lnk mdb pcd pif reg scr sct shs
+      vbe vba wsf wsh wsl msc msi msp mst
+    ].freeze
+
+    DEFAULT_CONTENT_TYPE = "application/octet-stream"
+
+    attr_reader :name, :content_type, :content_id
+
+    # @param content [String] raw (not Base64-encoded) bytes
+    def initialize(name:, content:, content_type: nil, content_id: nil)
+      @name = name.to_s
+      raise ArgumentError, "Attachment name is required" if @name.strip.empty?
+
+      self.class.assert_allowed!(@name)
+      @content = content.to_s.b
+      @content_type = content_type || self.class.guess_content_type(@name)
+      @content_id = self.class.normalize_content_id(content_id)
+    end
+
+    # "cid:logo.png" / "<logo.png>" -> "logo.png"; blank -> nil.
+    def self.normalize_content_id(value)
+      id = value.to_s.strip.delete_prefix("<").delete_suffix(">").sub(/\Acid:/i, "").strip
+      id = id.delete_prefix("<").delete_suffix(">").strip
+      return nil if id.empty?
+      raise ArgumentError, "Invalid ContentID #{value.inspect}" if id.match?(/[\s<>"\0]/)
+
+      id
+    end
+
+    def self.from_file(path, name: nil, content_type: nil, content_id: nil)
+      new(name: name || File.basename(path.to_s), content: File.binread(path),
+          content_type: content_type, content_id: content_id)
+    end
+
+    def self.assert_allowed!(filename)
+      extension = File.extname(filename.to_s).delete_prefix(".").downcase
+      return unless FORBIDDEN_EXTENSIONS.include?(extension)
+
+      raise ArgumentError, "Attachments with .#{extension} extension are rejected by Haskimail"
+    end
+
+    def self.guess_content_type(filename)
+      require "mini_mime"
+      MiniMime.lookup_by_filename(filename.to_s)&.content_type || DEFAULT_CONTENT_TYPE
+    rescue LoadError
+      DEFAULT_CONTENT_TYPE
+    end
+
+    def bytesize
+      @content.bytesize
+    end
+
+    def to_h
+      Util.compact(
+        "Name" => name,
+        "Content" => Base64.strict_encode64(@content),
+        "ContentType" => content_type,
+        "ContentID" => content_id
+      )
+    end
+    alias to_api to_h
+
+    def inspect
+      "#<#{self.class.name} name=#{name.inspect} content_type=#{content_type.inspect} bytes=#{bytesize}>"
+    end
+  end
+end

data/lib/haskimail/clients.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Haskimail
+  # Shared client behaviour: configuration, lazily built resources, safe #inspect.
+  class BaseClient
+    attr_reader :config
+
+    # @param token [String, nil] falls back to the global configuration
+    # @param options [Hash] per-client overrides of Haskimail::Configuration settings
+    def initialize(token = nil, **options)
+      @config = Haskimail.config.merge(options)
+      @connection = Connection.new(token: token || default_token, token_header: self.class::TOKEN_HEADER,
+                                   config: @config)
+    end
+
+    def inspect
+      "#<#{self.class.name} #{@connection.inspect}>"
+    end
+    alias to_s inspect
+
+    def self.resource(name, klass)
+      define_method(name) do
+        @resources ||= {}
+        @resources[name] ||= klass.new(@connection)
+      end
+    end
+    private_class_method :resource
+  end
+
+  # Client for everything that belongs to one server: sending, templates,
+  # messages, bounces, message streams, stats, webhooks, inbound rules, suppressions.
+  #
+  #   client = Haskimail::ServerClient.new(ENV["HASKIMAIL_SERVER_TOKEN"])
+  #   client.deliver(from: "shop@example.com", to: "ivan@example.com", subject: "Hi", text_body: "Hi")
+  class ServerClient < BaseClient
+    TOKEN_HEADER = "X-Haskimail-Server-Token"
+
+    resource :emails, Resources::Emails
+    resource :templates, Resources::Templates
+    resource :messages, Resources::Messages
+    resource :bounces, Resources::Bounces
+    resource :message_streams, Resources::MessageStreams
+    resource :stats, Resources::Stats
+    resource :webhooks, Resources::Webhooks
+    resource :inbound_rules, Resources::InboundRules
+    resource :suppressions, Resources::Suppressions
+
+    # Shortcuts for the most common calls.
+    def deliver(message) = emails.deliver(message)
+    def deliver_batch(messages) = emails.deliver_batch(messages)
+    def deliver_with_template(message) = emails.deliver_with_template(message)
+    def deliver_batch_with_templates(messages) = emails.deliver_batch_with_templates(messages)
+
+    private
+
+    def default_token
+      config.server_token
+    end
+  end
+
+  # Client for account-wide management: servers, domains, moving templates.
+  #
+  #   account = Haskimail::AccountClient.new(ENV["HASKIMAIL_ACCOUNT_TOKEN"])
+  #   account.domains.create("example.com")
+  class AccountClient < BaseClient
+    TOKEN_HEADER = "X-Haskimail-Account-Token"
+
+    resource :servers, Resources::Servers
+    resource :domains, Resources::Domains
+    resource :templates, Resources::AccountTemplates
+
+    private
+
+    def default_token
+      config.account_token
+    end
+  end
+end

data/lib/haskimail/configuration.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Haskimail
+  # Global and per-client settings.
+  #
+  #   Haskimail.configure do |config|
+  #     config.server_token  = Rails.application.credentials.dig(:haskimail, :server_token)
+  #     config.account_token = Rails.application.credentials.dig(:haskimail, :account_token)
+  #     config.default_message_stream = "2081"
+  #   end
+  class Configuration
+    DEFAULT_BASE_URL = "https://api.haskimail.ru"
+
+    SETTINGS = %i[
+      server_token account_token base_url open_timeout read_timeout write_timeout
+      max_retries retry_base_delay retry_max_delay logger default_message_stream
+      user_agent_suffix persistent_connections
+    ].freeze
+
+    attr_accessor(*SETTINGS)
+
+    def initialize
+      @server_token = ENV.fetch("HASKIMAIL_SERVER_TOKEN", nil)
+      @account_token = ENV.fetch("HASKIMAIL_ACCOUNT_TOKEN", nil)
+      @base_url = DEFAULT_BASE_URL
+      @open_timeout = 5
+      @read_timeout = 30
+      @write_timeout = 30
+      @max_retries = 2
+      @retry_base_delay = 0.5
+      @retry_max_delay = 8.0
+      @logger = nil
+      @default_message_stream = nil
+      @user_agent_suffix = nil
+      @persistent_connections = true
+    end
+
+    # Returns a copy with the given settings overridden; the receiver is untouched.
+    def merge(overrides)
+      unknown = overrides.keys.map(&:to_sym) - SETTINGS
+      raise ArgumentError, "Unknown Haskimail setting(s): #{unknown.join(', ')}" if unknown.any?
+
+      copy = dup
+      overrides.each { |key, value| copy.public_send(:"#{key}=", value) }
+      copy
+    end
+
+    def to_h
+      SETTINGS.to_h { |key| [key, public_send(key)] }
+    end
+
+    # Validates connection settings and returns the parsed base URI.
+    def base_uri
+      uri = URI.parse(base_url.to_s)
+      unless uri.is_a?(URI::HTTPS) && uri.host && !uri.host.empty?
+        raise ConfigurationError, "base_url must be an absolute https:// URL, got #{base_url.inspect}"
+      end
+      raise ConfigurationError, "base_url must not contain credentials" if uri.userinfo
+
+      uri
+    rescue URI::InvalidURIError => e
+      raise ConfigurationError, "Invalid base_url: #{e.message}"
+    end
+
+    SECRET_SETTINGS = %i[server_token account_token].freeze
+
+    def inspect
+      attrs = to_h.map do |key, value|
+        value = Util.redact(value) if SECRET_SETTINGS.include?(key)
+        "#{key}=#{value.inspect}"
+      end
+      "#<#{self.class.name} #{attrs.join(', ')}>"
+    end
+    alias to_s inspect
+
+    # Safe for logs and error trackers: tokens are redacted.
+    def as_json(*)
+      to_h.except(:logger).to_h do |key, value|
+        [key.to_s, SECRET_SETTINGS.include?(key) && value ? Secret::REDACTED : value]
+      end
+    end
+
+    def to_json(*args)
+      as_json.to_json(*args)
+    end
+  end
+end