zapsmtp 0.1.0.beta3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b3eecf99fc7d192df20863a57f9a728064f6b91e815c5a2dfda2ea4da5655116
+  data.tar.gz: 246b0b32ffddefa7069851bad0fd9533d872e19e96d6e17a4ce053aade020585
+SHA512:
+  metadata.gz: 9b767a2187a512585f43c94be011503b14575ce32a8fba60610abab52c838f1e3103c78d1e3579f970211918b7aee7729082cc041e8126c28876acb9ea9b55c9
+  data.tar.gz: e1ed416c5bcaaac0c78a381e6448b51322b0e91f2fa2f0bec40ef38a91a600de3508a3449fdd71224e3b690f583a9f6c4a3108d4cc9ebf5cf04921f258af89ef

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZapSMTP
+
+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,326 @@
+# ZapSMTP Ruby SDK
+
+The official Ruby library for the [ZapSMTP](https://zapsmtp.com) email API: send, receive and track
+email, manage templates, domains, webhooks and everything else the API does. It includes an
+ActionMailer delivery method for Rails.
+
+- Every API operation, with a reader for every documented response field
+- Safe automatic retries: sends carry an `Idempotency-Key`, so a retry never sends twice
+- Paging over every page of any list, lazily
+- Webhook signature verification, with a Rack middleware and a Rails controller concern
+- `config.action_mailer.delivery_method = :zapsmtp`
+- Ruby 3.0+, no dependencies beyond the standard library
+
+## Install
+
+```ruby
+# Gemfile
+gem "zapsmtp"
+```
+
+## Send an email
+
+```ruby
+require "zapsmtp"
+
+zap = ZapSMTP::Client.new(api_key: "zap_...") # or set ZAP_API_KEY and call ZapSMTP::Client.new
+
+email = zap.emails.send(
+  from: "Acme <hello@acme.com>",
+  to: "jane@example.org",
+  subject: "Your receipt",
+  html: "<p>Thanks for your order.</p>",
+  tags: [{ name: "category", value: "receipt" }],
+  metadata: { order_id: "A-1042" }
+)
+email.id # => "019a1f2e-..."
+```
+
+Parameters are keyword arguments, or a Hash, with the API's names (`reply_to`, `scheduled_at`...).
+A `Time` is sent as RFC 3339: `scheduled_at: Time.now + 3600`.
+
+With a template:
+
+```ruby
+zap.emails.send(
+  from: "Acme <hello@acme.com>",
+  to: "jane@example.org",
+  template: { id: "receipt", variables: { name: "Jane", total: 42 } }
+)
+```
+
+Attachments:
+
+```ruby
+zap.emails.send(
+  from: "Acme <hello@acme.com>",
+  to: "jane@example.org",
+  subject: "Your invoice",
+  html: '<p>Attached. <img src="cid:logo"></p>',
+  attachments: [
+    ZapSMTP::Attachment.from_file("invoice.pdf"),
+    ZapSMTP::Attachment.from_file("logo.png", content_id: "logo"), # inline
+    ZapSMTP::Attachment.from_string("report.csv", csv)
+  ]
+)
+```
+
+Up to 100 emails at once:
+
+```ruby
+result = zap.emails.send_batch(emails, validation: "permissive")
+result.data   # the sent ones
+result.errors # the refused ones, with their index
+```
+
+## Responses
+
+A response is a model with a reader for every documented field. Every field, documented or not,
+can be read with `[]` and `to_h` (keys as symbols), and models work with pattern matching:
+
+```ruby
+email = zap.emails.get(id)
+email.status      # => "delivered"
+email[:status]    # the same
+email.to_h        # => { id: "...", status: "delivered", ... }
+
+case email
+in { status: "bounced", to: } then suppress(to)
+end
+```
+
+A field the API adds later is kept, never an error. A field whose name is a Ruby method of every
+object, such as `method` on a log entry, is read with `[]`: `log[:method]`.
+
+## Lists
+
+A list call answers one page; `auto_paging_each` walks every page, asking for the next one only when
+the previous is used up.
+
+```ruby
+page = zap.emails.list(limit: 50, status: "bounced")
+page.data        # this page's emails
+page.next_page?  # makes no request
+page.next_page   # the next page, or nil
+
+zap.emails.list(status: "bounced").auto_paging_each do |email|
+  puts email.id
+end
+
+# an Enumerator: stop early without loading more pages
+zap.emails.list.auto_paging_each.lazy.select { |e| e.status == "bounced" }.first(10)
+```
+
+## Errors
+
+Every API error raises a `ZapSMTP::Error` subclass with `status`, `code`, `message`, `type`,
+`request_id`, `headers` and `body`.
+
+```ruby
+begin
+  zap.emails.send(**email)
+rescue ZapSMTP::ValidationError => e
+  warn "#{e.code}: #{e.message}" # e.g. invalid_parameter
+rescue ZapSMTP::RateLimitError => e
+  warn "retry in #{e.retry_after} s"
+end
+```
+
+| Class | When |
+|---|---|
+| `ZapSMTP::AuthenticationError` | 401: missing or invalid key |
+| `ZapSMTP::PermissionError` | 403: the key may not do this, or the domain is not verified |
+| `ZapSMTP::NotFoundError` | 404 |
+| `ZapSMTP::ConflictError` | 409 |
+| `ZapSMTP::ValidationError` | 400, 413, 422: the request is wrong (also an id that is empty, `.` or `..`, refused before sending) |
+| `ZapSMTP::RateLimitError` | 429: `retry_after` says how long to wait |
+| `ZapSMTP::ServerError` | 5xx |
+| `ZapSMTP::ConnectionError` | no answer: network failure or timeout (`cause` holds the underlying error) |
+
+## Retries and timeouts
+
+A request that failed on the way (429, 408, 5xx, a lost connection) is tried again twice by default,
+waiting as the API's `Retry-After` says or backing off exponentially. Only requests that are safe to
+repeat are retried: reads, updates by `PUT`, deletes, and sends, which always carry an
+`Idempotency-Key` (pass your own to make retries of your own safe too).
+
+```ruby
+zap = ZapSMTP::Client.new(api_key: "zap_...", max_retries: 4, timeout: 20)
+zap.emails.get(id, request_options: { timeout: 5, max_retries: 0 })
+zap.emails.send(**email, request_options: { idempotency_key: "order-1042-receipt" })
+```
+
+`request_options` takes `idempotency_key`, `headers`, `timeout` and `max_retries`.
+
+## Response headers
+
+Every model knows the answer it came from; `with_response` gives the response with any result,
+`nil` ones included:
+
+```ruby
+email = zap.emails.send(**email)
+email.http_response.request_id
+email.http_response["ratelimit-remaining"]
+
+result, response = zap.with_response.domains.delete(domain_id)
+response.status # => 204
+```
+
+## Template assets
+
+```ruby
+zap.template_assets.upload_file("logo.png", name: "Logo")       # a path (String or Pathname)
+zap.template_assets.upload_file(File.open("banner.webp"))       # or a File, StringIO...
+zap.template_assets.upload(url: "https://acme.com/logo.png")    # or a URL
+```
+
+## Webhooks
+
+Check the signature on the raw body, before parsing it. `verify` returns the event, or raises
+`ZapSMTP::WebhookVerificationError` when the signature is missing, wrong or older than five minutes.
+A webhook with batch delivery sends an array of events: use `verify_events`, which returns every
+event (one event as a list of one).
+
+```ruby
+event = ZapSMTP::Webhook.verify(raw_body, headers, ENV["ZAP_WEBHOOK_SECRET"])
+event.type # => "email.bounced"
+event.data # => { email_id: "...", to: "jane@example.org", ... }
+
+events = ZapSMTP::Webhook.verify_events(raw_body, headers, ENV["ZAP_WEBHOOK_SECRET"])
+```
+
+`headers` may be a Hash in any case, a Rack env, Rails' `request.headers`, or the `Zap-Signature`
+value itself. `zap.webhooks.verify` and `zap.webhooks.verify_events` do the same.
+
+Rails:
+
+```ruby
+class ZapsmtpWebhooksController < ActionController::API
+  include ZapSMTP::Rails::WebhookVerification # answers 400 to a request that fails verification
+
+  def create
+    event = zapsmtp_webhook_event # zapsmtp_webhook_events with batch delivery
+    Bounce.record!(event.data) if event.type == "email.bounced"
+    head :ok
+  end
+
+  private
+
+  # default: ENV["ZAP_WEBHOOK_SECRET"]
+  def zapsmtp_webhook_secret
+    Rails.application.credentials.zapsmtp_webhook_secret
+  end
+end
+```
+
+In an `ActionController::Base` controller, add `skip_forgery_protection`.
+
+Sinatra:
+
+```ruby
+post "/webhooks/zapsmtp" do
+  event = ZapSMTP::Webhook.verify(request.body.read, request.env, ENV["ZAP_WEBHOOK_SECRET"])
+  # ...
+  200
+rescue ZapSMTP::WebhookVerificationError
+  400
+end
+```
+
+Any Rack app, with the middleware (it answers 400 itself, and passes the events on in
+`env["zapsmtp.events"]`, and the one event of a request that is not a batch in
+`env["zapsmtp.event"]`):
+
+```ruby
+use ZapSMTP::WebhookMiddleware, path: "/webhooks/zapsmtp", secret: ENV["ZAP_WEBHOOK_SECRET"]
+```
+
+## Rails: the delivery method
+
+```ruby
+# config/environments/production.rb
+config.action_mailer.delivery_method = :zapsmtp
+config.action_mailer.zapsmtp_settings = { api_key: Rails.application.credentials.zapsmtp_api_key }
+```
+
+Mailers stay as they are. From, to, cc, bcc, reply-to, the subject, the HTML and text parts, custom
+headers (`In-Reply-To`, `List-Unsubscribe`, `X-...`) and attachments, inline ones included, go to
+`emails.send`. ZapSMTP's own options go in `zapsmtp:`:
+
+```ruby
+class UserMailer < ApplicationMailer
+  def welcome(user)
+    attachments.inline["logo.png"] = File.binread("app/assets/images/logo.png")
+    mail(
+      to: user.email,
+      subject: "Welcome, #{user.name}",
+      zapsmtp: {
+        tags: [{ name: "category", value: "welcome" }],
+        metadata: { user_id: user.id.to_s },
+        stream: "broadcast",
+        idempotency_key: "welcome-#{user.id}" # a retried job never sends twice
+      }
+    )
+  end
+
+  # a stored template: no view needed
+  def receipt(order)
+    mail(to: order.email, body: "", zapsmtp: {
+      template: { id: "receipt", variables: { total: order.total } },
+      subject: nil # nil: use the template's subject, not the mailer's
+    })
+  end
+end
+```
+
+The options travel in a private header, `X-Zapsmtp-Options`, which is never sent and is removed
+once the API has taken the message; any `emails.send` parameter can be set there. Every message is
+sent with an `Idempotency-Key`: yours, or one made on its first attempt and kept on the message, so
+delivering the same message again after a failure (a lost answer included) never sends it twice. After a send the message carries the email's id in
+`X-Zapsmtp-Email-Id`, and with `return_response: true` in the settings `deliver!` answers the API's
+response. API errors raise as above (ActionMailer's `raise_delivery_errors` applies).
+
+Settings: `api_key`, `base_url`, `timeout`, `max_retries`, `default_headers`, `transport`, or
+`client:` an existing `ZapSMTP::Client`.
+
+Without Rails, the Mail gem can use it too:
+
+```ruby
+require "zapsmtp/rails"
+
+message = Mail.new(from: "hello@acme.com", to: "jane@example.org", subject: "Hi", body: "Hello")
+ZapSMTP::Rails.set_options(message, { tags: [{ name: "category", value: "hello" }] })
+message.delivery_method(ZapSMTP::Rails::DeliveryMethod, api_key: ENV["ZAP_API_KEY"])
+message.deliver
+```
+
+## Configuration
+
+| Option | Environment | Default |
+|---|---|---|
+| `api_key` | `ZAP_API_KEY` | required |
+| `base_url` | `ZAP_BASE_URL` | `https://api.zapsmtp.com/v1` |
+| `timeout` | | 60 s per attempt: connecting, each write and each read, the body's included |
+| `max_retries` | | 2 |
+| `default_headers` | | |
+| `transport` | | `ZapSMTP::Transport::NetHTTP` (keeps a connection alive per thread) |
+
+A client is safe to share between threads, and a forked process (Puma, Unicorn) never reuses its
+parent's connections. A transport is any object with `call(request)`; tests can pass a stub.
+
+## Reference
+
+Every method is listed with its parameters in the [API reference](https://zapsmtp.com/docs/), and in
+the YARD docs of `lib/zapsmtp/generated/resources.rb`. The resources mirror it: `zap.emails`,
+`zap.emails.receiving`, `zap.threads`, `zap.domains`, `zap.webhooks`, `zap.actions`, `zap.templates`,
+`zap.variables`, `zap.template_modules`, `zap.template_assets`, `zap.template_timers`, `zap.inbound`,
+`zap.suppressions`, `zap.stats`, `zap.api_keys`, `zap.smtp_credentials`, `zap.logs`, `zap.usage`,
+`zap.simulator`, `zap.dedicated_ips`.
+
+## Development
+
+The resources and models in `lib/zapsmtp/generated` are generated from the API reference by
+`sdks/codegen` (`node sdks/codegen/generate.mjs --only ruby`); change the generator, never those
+files. `bundle exec rake` runs the tests (every API operation against the conformance server in
+`sdks/conformance`, the core, webhooks, the Rails integration; 100% line and branch coverage) and
+RuboCop.

data/lib/zapsmtp/attachment.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module ZapSMTP
+  # Builds attachments for emails.send: the content is sent base64-encoded,
+  # and the content type follows the file name's extension unless given.
+  #
+  #   zap.emails.send(..., attachments: [ZapSMTP::Attachment.from_file("invoice.pdf")])
+  #   ZapSMTP::Attachment.from_string("report.csv", csv)
+  #   ZapSMTP::Attachment.from_file("logo.png", content_id: "logo") # inline: <img src="cid:logo">
+  module Attachment
+    CONTENT_TYPES = {
+      ".pdf" => "application/pdf", ".png" => "image/png", ".jpg" => "image/jpeg", ".jpeg" => "image/jpeg",
+      ".gif" => "image/gif", ".webp" => "image/webp", ".svg" => "image/svg+xml", ".txt" => "text/plain",
+      ".csv" => "text/csv", ".html" => "text/html", ".ics" => "text/calendar", ".json" => "application/json",
+      ".xml" => "application/xml", ".zip" => "application/zip", ".doc" => "application/msword",
+      ".docx" => "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+      ".xls" => "application/vnd.ms-excel",
+      ".xlsx" => "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+    }.freeze
+
+    module_function
+
+    # An attachment from bytes or text.
+    #
+    # @param filename [String]
+    # @param data [String] the content (any encoding: its bytes are sent)
+    # @param content_type [String, nil] default: from the file name's extension
+    # @param content_id [String, nil] makes it inline: reference it as cid:<content_id>
+    # @return [Hash] filename, content (base64), content_type, content_id
+    def from_string(filename, data, content_type: nil, content_id: nil)
+      attachment = { filename: filename, content: [data.to_s].pack("m0") }
+      type = content_type || content_type_for(filename)
+      attachment[:content_type] = type if type
+      attachment[:content_id] = content_id if content_id
+      attachment
+    end
+
+    # An attachment read from a file.
+    #
+    # @param path [String, Pathname]
+    # @param filename [String, nil] default: the file's own name
+    # @return [Hash] filename, content (base64), content_type, content_id
+    def from_file(path, filename: nil, content_type: nil, content_id: nil)
+      from_string(filename || File.basename(path), File.binread(path),
+                  content_type: content_type, content_id: content_id)
+    end
+
+    # The content type of a file name's extension, when it is a known one.
+    #
+    # @return [String, nil]
+    def content_type_for(filename)
+      CONTENT_TYPES[File.extname(filename.to_s).downcase]
+    end
+  end
+end

data/lib/zapsmtp/base_client.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+
+module ZapSMTP
+  # The hand-written core of the client: HTTP, retries, errors and paging.
+  # The resources (ZapSMTP::Client) are generated from the API reference.
+  class BaseClient
+    DEFAULT_BASE_URL = "https://api.zapsmtp.com/v1"
+    USER_AGENT = "zapsmtp-ruby/#{VERSION} (ruby/#{RUBY_VERSION})".freeze
+    REQUEST_OPTIONS = %i[idempotency_key headers timeout max_retries].freeze
+    SAFE_METHODS = %w[GET PUT DELETE].freeze
+
+    # One API request, as the resources describe it.
+    #
+    # @api private
+    APIRequest = Struct.new(:http_method, :path, :query, :body, :form, :headers, :idempotent, keyword_init: true)
+
+    # @return [String]
+    attr_reader :api_key
+    # @return [String] without a trailing slash
+    attr_reader :base_url
+    # @return [Numeric] seconds per attempt
+    attr_reader :timeout
+    # @return [Integer] retries of a failed request that is safe to retry
+    attr_reader :max_retries
+    # @return [Hash{String => String}] headers sent with every request
+    attr_reader :default_headers
+    # @return [#call] see ZapSMTP::Transport
+    attr_reader :transport
+
+    # @param api_key [String, nil] default: ENV["ZAP_API_KEY"]
+    # @param base_url [String, nil] default: ENV["ZAP_BASE_URL"], else https://api.zapsmtp.com/v1
+    # @param timeout [Numeric] seconds per attempt (connecting, each write and each read)
+    # @param max_retries [Integer] retries of a failed request that is safe to retry
+    # @param default_headers [Hash{String => String}] sent with every request
+    # @param transport [#call, nil] default: ZapSMTP::Transport::NetHTTP
+    def initialize(api_key: nil, base_url: nil, timeout: 60, max_retries: 2, default_headers: {}, transport: nil)
+      @api_key = presence(api_key) || presence(ENV.fetch("ZAP_API_KEY", nil))
+      raise Error, "Missing API key: pass api_key: to ZapSMTP::Client.new or set ZAP_API_KEY" unless @api_key
+
+      @base_url = (presence(base_url) || presence(ENV.fetch("ZAP_BASE_URL", nil)) || DEFAULT_BASE_URL).sub(%r{/+\z}, "")
+      @timeout = timeout
+      @max_retries = max_retries
+      @default_headers = default_headers.to_h { |k, v| [k.to_s, v.to_s] }
+      @transport = transport || Transport::NetHTTP.new
+      @with_response = false
+      build_resources
+    end
+
+    # The same client, whose calls answer a ZapSMTP::Result: the data and the
+    # ZapSMTP::Response (status, headers, request id) together.
+    #
+    #   email, response = zap.with_response.emails.send(...)
+    #   response.request_id
+    #   response["ratelimit-remaining"]
+    #
+    # @return [ZapSMTP::Client]
+    def with_response
+      copy = dup
+      copy.instance_variable_set(:@with_response, true)
+      copy
+    end
+
+    def initialize_copy(other)
+      super
+      build_resources
+    end
+
+    def inspect
+      "#<#{self.class.name} base_url=#{base_url.inspect}>"
+    end
+
+    # @api private
+    def request(method:, path:, query: nil, body: nil, form: nil, headers: nil, idempotent: false, model: nil,
+                request_options: {})
+      req = APIRequest.new(http_method: method.to_s.upcase, path: path, query: query, body: body, form: form,
+                           headers: headers, idempotent: idempotent)
+      data, response = execute(req, request_options)
+      result = Model.build(model, data, response)
+      @with_response ? Result.new(result, response) : result
+    end
+
+    # @api private
+    def request_page(method:, path:, model:, paging:, query: nil, request_options: {})
+      req = APIRequest.new(http_method: method.to_s.upcase, path: path, query: query)
+      page = load_page(req, model, paging, request_options)
+      @with_response ? Result.new(page, page.http_response) : page
+    end
+
+    private
+
+    def build_resources; end
+
+    def presence(value)
+      value.nil? || value.to_s.empty? ? nil : value.to_s
+    end
+
+    def load_page(req, model, paging, request_options)
+      data, response = execute(req, request_options)
+      loader = ->(query) { load_page(req.dup.tap { |r| r.query = query }, model, paging, request_options) }
+      Page.new(data, model: model, query: req.query, paging: paging, loader: loader, http_response: response)
+    end
+
+    # Sends a request, retrying it as docs/DESIGN-sdks.md says; answers the
+    # parsed body and the response, or raises a ZapSMTP::Error.
+    def execute(req, request_options)
+      options = request_options(request_options)
+      attempt = build_attempt(req, options)
+      max_retries = options.fetch(:max_retries, @max_retries)
+      safe = SAFE_METHODS.include?(req.http_method) || req.idempotent == true
+      tries = 0
+      loop do
+        response, data, wait = attempt_once(attempt, safe, tries, tries < max_retries)
+        return [data, response] unless wait
+
+        sleep_for(wait)
+        tries += 1
+      end
+    end
+
+    # One attempt: [response, data, nil] on success, [nil, nil, seconds to
+    # wait] when it should be tried again; raises otherwise.
+    def attempt_once(attempt, safe, tries, may_retry)
+      begin
+        raw = @transport.call(attempt)
+      rescue StandardError => e
+        # a timeout or a broken connection (sending, or reading the answer):
+        # the request may have reached the server, so only a request that is
+        # safe to repeat is sent again
+        return [nil, nil, Retry.backoff(tries, nil)] if may_retry && safe
+
+        raise connection_error(e)
+      end
+      response = Response.new(raw.status.to_i, normalize_headers(raw.headers))
+      data = parse(raw.body)
+      return [response, data, nil] if response.status.between?(200, 299)
+
+      error = Error.from_response(response.status, data, response.headers)
+      raise error unless may_retry && Retry.retryable?(response.status, error.code, safe)
+
+      [nil, nil, Retry.backoff(tries, Retry.retry_after(response.headers))]
+    end
+
+    # A failed attempt as a ConnectionError; when the answer's head came
+    # before its body broke off, with its status, headers and request id.
+    def connection_error(error)
+      return ConnectionError.new(error.message) unless error.is_a?(Transport::ResponseBodyError)
+
+      headers = normalize_headers(error.headers)
+      ConnectionError.new(error.message, status: error.status, headers: headers, request_id: headers["x-request-id"])
+    end
+
+    def build_attempt(req, options)
+      headers = attempt_headers(req, options)
+      body = nil
+      if req.form
+        headers["Content-Type"] = req.form.content_type
+        body = req.form.body
+      elsif !req.body.nil?
+        headers["Content-Type"] = "application/json"
+        body = JSON.generate(Util.jsonable(req.body))
+      end
+      Transport::Request.new(http_method: req.http_method, url: url(req), headers: headers, body: body,
+                             timeout: options.fetch(:timeout, @timeout))
+    end
+
+    # The headers of a request. Later ones replace earlier ones whatever
+    # their case: the client's defaults, the operation's, the
+    # Idempotency-Key, the caller's.
+    def attempt_headers(req, options)
+      headers = { "Authorization" => "Bearer #{@api_key}", "Accept" => "application/json", "User-Agent" => USER_AGENT }
+      @default_headers.each { |k, v| set_header(headers, k, v) }
+      (req.headers || {}).each { |k, v| set_header(headers, k, v) unless v.nil? }
+      set_header(headers, "Idempotency-Key", options[:idempotency_key] || SecureRandom.uuid) if req.idempotent
+      (options[:headers] || {}).each { |k, v| set_header(headers, k, v) }
+      # an empty key turns deduplication off on the server, so a retried
+      # send could go out twice: refused before anything is sent
+      key = headers.find { |k, _| k.casecmp?("idempotency-key") }
+      if key && key[1].strip.empty?
+        raise ValidationError.new("idempotency_key must not be empty", code: "invalid_parameter")
+      end
+
+      headers
+    end
+
+    def set_header(headers, name, value)
+      name = name.to_s
+      headers.delete_if { |k, _| k.casecmp?(name) }
+      headers[name] = value.to_s
+    end
+
+    def url(req)
+      query = Util.query_string(req.query)
+      query.empty? ? "#{@base_url}#{req.path}" : "#{@base_url}#{req.path}?#{query}"
+    end
+
+    def request_options(options)
+      options = (options || {}).transform_keys(&:to_sym)
+      unknown = options.keys - REQUEST_OPTIONS
+      raise ArgumentError, "unknown request option(s): #{unknown.join(", ")}" unless unknown.empty?
+
+      options
+    end
+
+    def normalize_headers(headers)
+      (headers || {}).each_with_object({}) do |(k, v), out|
+        out[k.to_s.downcase] = v.is_a?(Array) ? v.join(", ") : v.to_s
+      end
+    end
+
+    def parse(body)
+      return nil if body.nil? || body.empty?
+
+      Util.finite(JSON.parse(body, symbolize_names: true, allow_nan: true))
+    rescue JSON::ParserError
+      body
+    end
+
+    def sleep_for(seconds)
+      sleep(seconds)
+    end
+  end
+end

data/lib/zapsmtp/core.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Everything but the Rails integration (lib/zapsmtp.rb adds it when Rails is loaded).
+require_relative "version"
+require_relative "errors"
+require_relative "response"
+require_relative "model"
+require_relative "page"
+require_relative "util"
+require_relative "attachment"
+require_relative "retry"
+require_relative "transport"
+require_relative "base_client"
+require_relative "webhook"
+require_relative "webhook_middleware"
+require_relative "generated/models"
+require_relative "generated/resources"
+require_relative "generated/client"