mailkube 1.0.0

data/lib/mailkube/logging.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Mailkube
+  # Opt-in request logging: silent by default, and never a secret on the way out.
+  #
+  # Deliberately **not** built on stdlib `Logger`. `logger` stopped being a default gem in Ruby
+  # 4.0, so `require "logger"` inside this gem raises under Bundler on a Ruby this gem supports,
+  # and declaring it would cost the gem its zero-dependency claim — the same trap that keeps
+  # `Base64` out of {Serialization}. A library also has no business installing handlers, levels or
+  # formatters on its host's behalf.
+  #
+  # So the sink is any object responding to `#write(String)`: `$stderr`, a `File`, a `StringIO`,
+  # or a two-line shim over your application's own logger. That is the same dependency-inversion
+  # seam `Client.new(http:)` already uses, and it is what makes `Mailkube.enable_logging(device:
+  # Rails.logger)` work without this gem knowing what Rails is.
+  #
+  # This is the one piece of mutable module state in the gem. {enable!} and {disable!} are
+  # boot-time calls from the main thread; assigning one object reference is atomic, and no request
+  # path ever writes here.
+  module Logging
+    # Environment variable that turns logging on without a code change. It holds a **level**.
+    ENV_LEVEL = "MAILKUBE_LOG"
+    # The `MAILKUBE_LOG` values verbose enough to let this SDK's records through.
+    #
+    # `MAILKUBE_LOG` is a level, not a flag, in every mailkube SDK. This one emits exactly one
+    # class of record, the request/response trace, and that record is debug-level — so a level
+    # more selective than debug must silence it. `MAILKUBE_LOG=warning` is a working way to say
+    # "logs, but not from the SDK", and it has to keep working here or the variable means
+    # something different in Ruby than in python, node, Go and PHP.
+    VERBOSE_LEVELS = %w[trace debug all].freeze
+    # The headers whose values are masked before anything is written.
+    SENSITIVE_HEADERS = %w[authorization idempotency-key].freeze
+    # What a masked header value is replaced with.
+    REDACTION = "***"
+
+    @device = nil
+
+    # @return [#write, nil] where SDK logging is written, or nil when it is off.
+    def self.device = @device
+
+    # Turn logging on.
+    #
+    # @param device [#write] where to write; anything responding to `#write(String)`.
+    # @return [#write] the device now in use.
+    def self.enable!(device: $stderr) = @device = device
+
+    # Turn logging back off. The inverse of {enable!}, for a suite that turned it on.
+    #
+    # @return [nil] always.
+    def self.disable! = @device = nil
+
+    # Turn logging on from the environment, when `MAILKUBE_LOG` names a level of {VERBOSE_LEVELS}.
+    #
+    # Called once from `mailkube.rb`, so a deployment can turn logging on without a code change.
+    # It takes the environment as an argument rather than reading `ENV` inline because a bare `if`
+    # at the bottom of a file runs exactly once at load: no spec could reach its second branch, and
+    # the branch-coverage gate would then be paying for a line nobody can test.
+    #
+    # An unrecognized value leaves logging **off** rather than raising. This runs at `require`
+    # time, and no environment variable should be able to make `require "mailkube"` fail.
+    #
+    # @param env [Hash] the environment to read.
+    # @return [#write, nil] the device now in use, or nil when the level does not admit this SDK.
+    def self.enable_from_env(env = ENV)
+      level = env[ENV_LEVEL]
+      return nil unless VERBOSE_LEVELS.include?(level.to_s.strip.downcase)
+
+      enable!
+    end
+
+    # A copy of `headers` with every secret value masked, safe to write anywhere.
+    #
+    # @param headers [Hash{String => String}] the headers about to be logged.
+    # @return [Hash{String => String}] the redacted copy; the caller's hash is not modified.
+    #
+    # Accumulated into an annotated hash rather than returned from `to_h { [k, v] }`, for the same
+    # reason as {Serialization.query}: Steep types a two-element array literal in block-body
+    # position as `Array[String]`, not as the tuple `to_h` declares.
+    def self.redact(headers)
+      masked = {} #: Hash[String, String]
+      headers.each { |name, value| masked[name] = SENSITIVE_HEADERS.include?(name.downcase) ? REDACTION : value }
+      masked
+    end
+
+    # Log one outgoing request, with its headers redacted.
+    #
+    # The `&.` is not a nil-check bolted onto a log line: it **is** "silent by default", and it is
+    # why {redact} costs nothing for the callers who never enable logging — which is what lets this
+    # call sit on the request path at all.
+    #
+    # @param method [String] the HTTP method.
+    # @param url [String] the absolute URL.
+    # @param headers [Hash{String => String}] the merged request headers.
+    # @return [void]
+    def self.request(method, url, headers)
+      @device&.write("mailkube > #{method} #{url} #{redact(headers)}\n")
+    end
+
+    # Log one response, including the server's request id when it sent one.
+    #
+    # The id is what makes a support ticket traceable: the customer finds the failing call in
+    # their own logs and quotes the same value the API recorded. It is an id, not content — no
+    # recipient, subject or body reaches a log record here or anywhere else in this module.
+    #
+    # @param status [Integer] the HTTP status code.
+    # @param url [String] the absolute URL.
+    # @param request_id [String, nil] the `X-Request-Id` header, when the response carried one.
+    # @return [void]
+    def self.response(status, url, request_id = nil)
+      @device&.write("mailkube < #{status} #{url}#{request_id.nil? ? "" : " request_id=#{request_id}"}\n")
+    end
+  end
+end

data/lib/mailkube/net_http_adapter.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "socket"
+require "timeout"
+require "uri"
+
+module Mailkube
+  # The default HTTP adapter, and the only file in this gem that touches `Net::HTTP`.
+  #
+  # ## The adapter contract
+  #
+  # An adapter responds to `#call(method:, url:, headers:, body:)` and returns an
+  # {HttpResponse}. It raises {ConnectionError} when the request never produced a response, and
+  # raises nothing else: mapping an HTTP status to an exception is {Transport}'s job, so a
+  # replacement adapter never has to know the API's error envelope.
+  #
+  # Pass your own through `Client.new(http:)` to route through a proxy, add instrumentation, or
+  # drive the client from a test.
+  #
+  # ## Why a fresh connection per request
+  #
+  # `Net::HTTP.start` opens a connection, yields, and closes it. Sharing one `Net::HTTP` instance
+  # across callers is not a crash bug, it is **response cross-talk**: two threads interleave on
+  # one socket and one receives the other's body. Inside a single process that is a
+  # confidentiality bug, and it is exactly what `spec/concurrency_spec.rb` exists to catch.
+  #
+  # Connection reuse is therefore left to whoever needs it, with the reason stated: a correct
+  # pool has to be safe under threads **and** under a fiber scheduler, which is more than a
+  # scaffold should assume on a caller's behalf.
+  class NetHttpAdapter
+    # The HTTP verbs this adapter can issue, mapped to their `Net::HTTP` request classes.
+    #
+    # A frozen table rather than `const_get` on a caller-supplied string, which would turn a
+    # method name into an arbitrary constant lookup.
+    METHODS = {
+      "GET" => Net::HTTP::Get,
+      "POST" => Net::HTTP::Post,
+      "PATCH" => Net::HTTP::Patch,
+      "DELETE" => Net::HTTP::Delete
+    }.freeze
+
+    # Errors `Net::HTTP` raises when no response was produced. Each becomes a {ConnectionError}.
+    TRANSPORT_ERRORS = [
+      IOError,
+      SocketError,
+      SystemCallError,
+      Timeout::Error,
+      OpenSSL::SSL::SSLError,
+      Net::HTTPBadResponse,
+      Net::ProtocolError
+    ].freeze
+
+    # @param timeout [Integer, Float] the open and read timeout in seconds.
+    def initialize(timeout: Config::DEFAULT_TIMEOUT)
+      @timeout = timeout
+      freeze
+    end
+
+    # Perform one HTTP round trip.
+    #
+    # @param method [String] the HTTP method; must be a key of {METHODS}.
+    # @param url [String] the absolute URL to request.
+    # @param headers [Hash{String => String}] the request headers.
+    # @param body [String, nil] the already-serialized request body.
+    # @return [HttpResponse] the response.
+    # @raise [ConnectionError] when the request produced no response.
+    def call(method:, url:, headers:, body: nil)
+      uri = parse_url(url)
+      # `Config#build_url` only ever produces a URL with a host, but this adapter is public and
+      # can be driven directly, so the guard is real rather than defensive noise.
+      host = uri.hostname
+      raise ConfigurationError, "URL has no host: #{url.inspect}" if host.nil?
+
+      request = build_request(method, uri, headers, body)
+
+      Net::HTTP.start(host, uri.port, use_ssl: uri.scheme == "https",
+                                      open_timeout: @timeout, read_timeout: @timeout) do |http|
+        to_response(http.request(request))
+      end
+    rescue *TRANSPORT_ERRORS => e
+      raise ConnectionError, "#{e.class}: #{e.message}"
+    end
+
+    private
+
+    # Parse the URL, keeping `URI`'s own exception out of the caller's rescue clauses.
+    #
+    # Everything this adapter can refuse already raises {ConfigurationError} — an unsupported verb,
+    # a URL with no host — and a malformed URL was the one case where a foreign type escaped
+    # instead. `rescue Mailkube::Error` is the documented way to catch anything this gem raises,
+    # so a bare `URI::InvalidURIError` reaching a caller made that promise false. The adapter is
+    # public and can be driven directly, so this is reachable without going through
+    # {Config#build_url}, which already maps the same two exceptions the same way.
+    #
+    # @param url [String] the URL to parse.
+    # @return [URI::Generic] the parsed URL.
+    # @raise [ConfigurationError] when the URL cannot be parsed.
+    def parse_url(url)
+      URI.parse(url)
+    rescue URI::InvalidURIError, URI::InvalidComponentError => e
+      raise ConfigurationError, "invalid URL #{url.inspect}: #{e.message}"
+    end
+
+    # @return [Net::HTTPRequest] the request object for a method, URL, headers and body.
+    def build_request(method, uri, headers, body)
+      request_class = METHODS.fetch(method.upcase) do
+        raise ConfigurationError, "unsupported HTTP method #{method.inspect}"
+      end
+      request = request_class.new(uri)
+      headers.each { |name, value| request[name] = value }
+      request.body = body unless body.nil?
+      request
+    end
+
+    # @return [HttpResponse] the adapter-neutral view of a `Net::HTTPResponse`.
+    def to_response(raw)
+      headers = raw.each_header.to_h { |name, value| [name.downcase, value] }
+      HttpResponse.new(status: raw.code.to_i, headers: headers, body: raw.body.to_s)
+    end
+  end
+end

data/lib/mailkube/resources/emails.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Mailkube
+  module Resources
+    # The `emails` namespace, reached as `client.emails`.
+    #
+    # This is the worked example every new resource copies. Note what it does *not* do: it holds
+    # no configuration, performs no I/O, and never requires `net/http`. It depends only on an
+    # object responding to the one verb it calls.
+    class Emails
+      # @param transport [#send_email] the transport performing this resource's requests.
+      def initialize(transport)
+        @transport = transport
+        freeze
+      end
+
+      # Send an email.
+      #
+      # Supply `html` and/or `text` for a raw send, or `template_id` for a saved template.
+      # `idempotency_key` travels as the `Idempotency-Key` header rather than in the body.
+      # Passing `scheduled_at` schedules the send instead of delivering it now; the result then
+      # reports {Email#scheduled?}.
+      #
+      # This method shadows `Object#send` **on this object only**, which is deliberate: every
+      # mailkube SDK spells the verb `emails.send`, and a Ruby-only name would break that. Use
+      # `__send__` if you need reflective dispatch on a resource.
+      #
+      # @param from [String] the sender address, optionally with a display name.
+      # @param to [String, Array<String>] the recipient address or addresses.
+      # @param subject [String] the subject line.
+      # @param html [String, nil] the HTML body, for a raw-content send.
+      # @param text [String, nil] the plain-text body, for a raw-content send.
+      # @param cc [Array<String>, nil] carbon-copy recipients.
+      # @param bcc [Array<String>, nil] blind carbon-copy recipients.
+      # @param reply_to [String, Array<String>, nil] the Reply-To addresses.
+      # @param headers [Hash{String => String}, nil] custom message headers.
+      # @param attachments [Array<Attachment>, nil] the file attachments.
+      # @param tags [Array<Tag>, nil] free-form name/value tags forwarded to the server.
+      # @param template_id [String, nil] the UUID of a saved template to render.
+      # @param template_version [String, nil] a template version number, or "latest".
+      # @param variables [Hash, nil] values for the template's placeholders.
+      # @param topic [String, nil] the mailing-list topic slug this send is attributed to.
+      # @param idempotency_key [String, nil] sent as the `Idempotency-Key` header.
+      # @param scheduled_at [Time, String, nil] schedules the send instead of sending now.
+      # @param batch_id [String, nil] groups several scheduled sends.
+      # @return [Email] the accepted-send result.
+      # @raise [APIError] on any non-2xx response.
+      # @raise [ConnectionError] on a transport failure or timeout.
+      def send(from:, to:, subject:, html: nil, text: nil, cc: nil, bcc: nil, reply_to: nil, headers: nil,
+               attachments: nil, tags: nil, template_id: nil, template_version: nil, variables: nil,
+               topic: nil, idempotency_key: nil, scheduled_at: nil, batch_id: nil)
+        # One hash literal, then a single `compact`, rather than a chain of `body["x"] = x if x`.
+        # That keeps this method's cyclomatic complexity at 1 no matter how many optional fields
+        # the API grows, and is why an unset field is absent from the wire rather than null.
+        body = {
+          "from" => from, "to" => to, "subject" => subject,
+          "html" => html, "text" => text, "cc" => cc, "bcc" => bcc,
+          "reply_to" => reply_to, "headers" => headers,
+          "attachments" => Serialization.encode_attachments(attachments),
+          "tags" => Serialization.encode_tags(tags),
+          "template_id" => template_id, "template_version" => template_version,
+          "variables" => variables, "topic" => topic,
+          "scheduled_at" => Serialization.to_iso(scheduled_at), "batch_id" => batch_id
+        }.compact
+
+        @transport.send_email(RequestSpec.new(path: "emails", body: body, headers: idempotency(idempotency_key)))
+      end
+
+      private
+
+      # Build the body as one hash literal and drop the nils in a single pass, rather than a
+      # chain of `body["x"] = x if x`. That keeps this method's cyclomatic complexity at 1 no
+      # matter how many optional fields the API grows, and is why an unset field is absent from
+      # the wire rather than sent as null.
+      #
+      # @param key [String, nil] the caller's idempotency key.
+      # @return [Hash{String => String}] the per-request headers.
+      def idempotency(key) = key.nil? ? {} : { "Idempotency-Key" => key }
+    end
+  end
+end

data/lib/mailkube/resources/scheduled_email_requests.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Mailkube
+  module Resources
+    # The request builders for the `scheduled-emails` routes.
+    #
+    # Standalone builders, one per verb, exactly as the contract requires — and here they earn
+    # their keep twice over. Eight verbs across two collections differ only in a path constant and
+    # a method string; written inline they would be eight near-identical bodies and the duplication
+    # gate would say so. Funnelled through {item} they are one-liners, and the escaping rule is
+    # applied in exactly one place.
+    module ScheduledEmailRequests
+      # The collection path.
+      COLLECTION = "scheduled-emails"
+      # The batch sub-collection path. Sub-resources mirror sub-paths, so this is a path rather
+      # than a suffix bolted onto a verb name.
+      BATCHES = "scheduled-emails/batches"
+
+      # The one item request every single-resource verb is built from.
+      #
+      # @param base [String] the collection path.
+      # @param identifier [String] the id or batch label to interpolate.
+      # @param method [String] the HTTP method.
+      # @param body [Hash, nil] the JSON body, or nil for a body-less request.
+      # @return [RequestSpec] the request.
+      def self.item(base, identifier, method, body = nil)
+        RequestSpec.new(path: "#{base}/#{Serialization.escape_segment(identifier)}", method: method, body: body)
+      end
+      private_class_method :item
+
+      # Build the listing request.
+      #
+      # Filters are named here rather than splatted so the five the API supports exist in exactly
+      # one place. An omitted filter is dropped by {Serialization.query}, and no filters at all
+      # yields no query string rather than a bare `?`.
+      #
+      # @param status [String, Array<String>, nil] one status, or several.
+      # @param batch_id [String, nil] only emails grouped under this batch label.
+      # @param scheduled_at_gte [Time, String, nil] only emails due at or after this instant.
+      # @param scheduled_at_lte [Time, String, nil] only emails due at or before this instant.
+      # @param page [Integer, nil] the 1-based page number.
+      # @return [RequestSpec] the listing request.
+      def self.list(status: nil, batch_id: nil, scheduled_at_gte: nil, scheduled_at_lte: nil, page: nil)
+        filters = { status: status, batch_id: batch_id, scheduled_at_gte: scheduled_at_gte,
+                    scheduled_at_lte: scheduled_at_lte, page: page }
+        RequestSpec.new(path: COLLECTION, method: "GET", params: Serialization.query(filters))
+      end
+
+      # @param url [String] an absolute page link the API issued; it carries its own query.
+      # @return [RequestSpec] the request for that page.
+      def self.page(url) = RequestSpec.new(path: url, method: "GET")
+
+      # @param email_id [String] the scheduled email's id.
+      # @return [RequestSpec] the retrieval request.
+      def self.get(email_id) = item(COLLECTION, email_id, "GET")
+
+      # @param email_id [String] the scheduled email's id.
+      # @param body [Hash] the new due time, and optionally a batch to move the email into.
+      # @return [RequestSpec] the reschedule request.
+      def self.update(email_id, body) = item(COLLECTION, email_id, "PATCH", body)
+
+      # @param email_id [String] the scheduled email's id.
+      # @return [RequestSpec] the cancellation request.
+      def self.cancel(email_id) = item(COLLECTION, email_id, "DELETE")
+
+      # @param batch_id [String] the batch label.
+      # @param body [Hash] the new due time. There is deliberately no `batch_id` in it: the batch
+      #   is identified by the path, and the server rejects a second one in the body rather than
+      #   let it decide which batch actually moves.
+      # @return [RequestSpec] the batch reschedule request.
+      def self.batch_update(batch_id, body) = item(BATCHES, batch_id, "PATCH", body)
+
+      # @param batch_id [String] the batch label.
+      # @return [RequestSpec] the batch cancellation request.
+      def self.batch_cancel(batch_id) = item(BATCHES, batch_id, "DELETE")
+    end
+  end
+end

data/lib/mailkube/resources/scheduled_emails.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Mailkube
+  module Resources
+    # Batch operations, reached as `client.scheduled_emails.batches`.
+    #
+    # A sibling resource sharing the enclosing namespace's transport, not a method group: the wire
+    # has a `scheduled-emails/batches/{id}` sub-path, so the SDK has a sub-namespace. A
+    # `update_batch` suffix would flatten a structure the API actually has.
+    class ScheduledEmailBatches
+      # @param transport [#request_json] the transport performing this resource's requests.
+      def initialize(transport)
+        @transport = transport
+        freeze
+      end
+
+      # Reschedule every pending email in a batch.
+      #
+      # @param batch_id [String] the batch label.
+      # @param scheduled_at [Time, String] the new due time, in the future and within the plan's
+      #   scheduling horizon. ISO-8601 with an offset, or a Time.
+      # @return [ScheduledEmailBatchUpdate] how many emails moved, and where to.
+      # @raise [APIError] on any non-2xx response.
+      def update(batch_id, scheduled_at:)
+        body = { "scheduled_at" => Serialization.to_iso(scheduled_at) }
+        ScheduledEmailBatchUpdate.from(@transport.request_json(ScheduledEmailRequests.batch_update(batch_id, body)))
+      end
+
+      # Cancel every pending email in a batch.
+      #
+      # An unknown batch is a no-op reporting a count of 0 rather than a 404, so a count of 0 is
+      # not a failure.
+      #
+      # @param batch_id [String] the batch label.
+      # @return [ScheduledEmailBatchCancel] how many emails were cancelled.
+      # @raise [APIError] on any non-2xx response.
+      def cancel(batch_id)
+        ScheduledEmailBatchCancel.from(@transport.request_json(ScheduledEmailRequests.batch_cancel(batch_id)))
+      end
+    end
+
+    # The `scheduled_emails` namespace, reached as `client.scheduled_emails`.
+    #
+    # Sends made with `scheduled_at:` are manageable here until they are due. A sent email has left
+    # the collection, so `status: "sent"` is a validation error rather than an empty result.
+    class ScheduledEmails
+      # @return [ScheduledEmailBatches] the batch operations.
+      attr_reader :batches
+
+      # @param transport [#request_json] the transport performing this resource's requests.
+      def initialize(transport)
+        @transport = transport
+        @batches = ScheduledEmailBatches.new(transport)
+        freeze
+      end
+
+      # List one page of scheduled emails.
+      #
+      # Every filter is optional and an omitted one never reaches the wire. A list of statuses
+      # becomes one comma-joined parameter rather than a repeated one. The listing is scoped
+      # server-side to a rolling window around now, so a bound in the direction that can never
+      # match is rejected rather than silently returning nothing.
+      #
+      # @param status [String, Array<String>, nil] one status, or several. Only `scheduled`,
+      #   `canceled` and `failed` can be listed.
+      # @param batch_id [String, nil] only emails grouped under this batch label.
+      # @param scheduled_at_gte [Time, String, nil] only emails due at or after this instant.
+      # @param scheduled_at_lte [Time, String, nil] only emails due at or before this instant.
+      # @param page [Integer, nil] the 1-based page number to fetch.
+      # @return [ScheduledEmailPage] one page, plus its pagination block.
+      # @raise [APIError] on any non-2xx response.
+      def list(status: nil, batch_id: nil, scheduled_at_gte: nil, scheduled_at_lte: nil, page: nil)
+        fetch_page(ScheduledEmailRequests.list(status: status, batch_id: batch_id,
+                                               scheduled_at_gte: scheduled_at_gte,
+                                               scheduled_at_lte: scheduled_at_lte, page: page))
+      end
+
+      # Iterate every scheduled email matching the filters, across every page.
+      #
+      # Lazy: no request is made until the enumerator is iterated, and abandoning it early costs
+      # nothing. Pages advance by **following the server's `next` link**, never by incrementing a
+      # counter, so the server stays free to change its pagination scheme. The link is fetched
+      # through {Config#build_url}, which refuses one off the configured origin — every request
+      # carries the API key, so a link naming a foreign host must not be followed.
+      #
+      # @param (see #list)
+      # @return [Enumerator<ScheduledEmail>] every matching scheduled email, page after page.
+      def iter_all(status: nil, batch_id: nil, scheduled_at_gte: nil, scheduled_at_lte: nil, page: nil)
+        Enumerator.new do |yielder|
+          current = list(status: status, batch_id: batch_id, scheduled_at_gte: scheduled_at_gte,
+                         scheduled_at_lte: scheduled_at_lte, page: page)
+          loop do
+            current.data.each { |item| yielder << item }
+            link = current.pagination.steps.next
+            break if link.nil?
+
+            current = fetch_page(ScheduledEmailRequests.page(link))
+          end
+        end
+      end
+
+      # Retrieve one scheduled email.
+      #
+      # @param email_id [String] the id the scheduled-send acknowledgement returned.
+      # @return [ScheduledEmail] the scheduled email.
+      # @raise [NotFoundError] when no such scheduled email exists, which is also what an id
+      #   belonging to another organization reports.
+      def get(email_id)
+        ScheduledEmail.from(@transport.request_json(ScheduledEmailRequests.get(email_id)))
+      end
+
+      # Reschedule one scheduled email, optionally moving it into or out of a batch.
+      #
+      # The content of a scheduled email is immutable; only its due time and batch can change.
+      #
+      # @param email_id [String] the id the scheduled-send acknowledgement returned.
+      # @param scheduled_at [Time, String] the new due time.
+      # @param batch_id [String, nil] a batch to move the email into.
+      # @return [ScheduledEmail] the rescheduled email.
+      # @raise [InvalidRequestError] when the email is no longer pending.
+      def update(email_id, scheduled_at:, batch_id: nil)
+        body = { "scheduled_at" => Serialization.to_iso(scheduled_at), "batch_id" => batch_id }.compact
+        ScheduledEmail.from(@transport.request_json(ScheduledEmailRequests.update(email_id, body)))
+      end
+
+      # Cancel one scheduled email before it is sent.
+      #
+      # @param email_id [String] the id the scheduled-send acknowledgement returned.
+      # @return [CanceledScheduledEmail] the cancellation acknowledgement.
+      # @raise [InvalidRequestError] when the email is no longer pending.
+      def cancel(email_id)
+        CanceledScheduledEmail.from(@transport.request_json(ScheduledEmailRequests.cancel(email_id)))
+      end
+
+      private
+
+      # @param spec [RequestSpec] the page request.
+      # @return [ScheduledEmailPage] the parsed page.
+      def fetch_page(spec) = ScheduledEmailPage.from(@transport.request_json(spec))
+    end
+  end
+end

data/lib/mailkube/serialization.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "time"
+require "erb/util"
+
+module Mailkube
+  # How a Ruby value becomes JSON, a query-string parameter, or a path segment.
+  #
+  # One home for every "how does this go on the wire" decision, shared by every resource. Nothing
+  # here validates: the server is the authority on what a value means, and its error names are
+  # richer than anything the SDK would reproduce. These functions only make values transmissible.
+  module Serialization
+    # Render an instant for a JSON body, passing an already-formatted string through.
+    #
+    # Returns nil for nil on purpose: that is what lets a request body be one hash literal followed
+    # by a single `compact`, and why an unset field is absent from the wire rather than sent as
+    # null. Compare {query_value}, which can never return nil.
+    #
+    # @param value [Time, String, nil] the caller's instant.
+    # @return [String, nil] the ISO-8601 rendering, or nil.
+    def self.to_iso(value) = value.is_a?(Time) ? value.iso8601 : value
+
+    # Render one query-string parameter, **always** as a String.
+    #
+    # A list becomes a comma-joined value rather than a repeated parameter: the API accepts both,
+    # and a flat `Hash[String, String]` keeps the transport seam simple in every SDK that mirrors
+    # this design. A query string has no types, which is why this cannot just call {to_iso}: that
+    # would hand back the Integer `2` for `page: 2`.
+    #
+    # @param value [Object] a scalar, a Time, or an array of either.
+    # @return [String] the parameter's string form.
+    def self.query_value(value)
+      return value.map { |item| query_scalar(item) }.join(",") if value.is_a?(Array)
+
+      query_scalar(value)
+    end
+
+    # @param value [Object] one scalar parameter value.
+    # @return [String] its string form.
+    def self.query_scalar(value) = value.is_a?(Time) ? value.iso8601 : value.to_s
+    private_class_method :query_scalar
+
+    # Render a whole filter set for the query string, dropping the filters the caller omitted.
+    #
+    # `compact` is what makes both wire rules true in one pass, at a cyclomatic complexity of 1:
+    # an omitted filter never reaches the wire, and no filters at all yields an empty hash, which
+    # {Config#build_url} turns into no query string rather than a bare `?`.
+    #
+    # @param filters [Hash{Symbol => Object}] the caller's filters, nils included.
+    # @return [Hash{String => String}] the query parameters.
+    #
+    # Accumulated into an annotated hash rather than returned from `to_h { [k, v] }`, because Steep
+    # infers a two-element array literal in block-body position as `Array[String]`, not as the
+    # `[String, String]` tuple `to_h`'s signature demands, and reports a `BlockBodyTypeMismatch`
+    # that no annotation on the block can settle.
+    def self.query(filters)
+      rendered = {} #: Hash[String, String]
+      filters.compact.each { |name, value| rendered[name.to_s] = query_value(value) }
+      rendered
+    end
+
+    # Escape one interpolated path segment.
+    #
+    # `ERB::Util.url_encode`, and specifically **not** `CGI.escape` or
+    # `URI.encode_www_form_component`: those render a space as `+`, which is the form-encoding rule
+    # for a query string, not the percent-encoding rule for a path segment. It is also not
+    # cosmetic — an identifier carrying an encoded `/` or `?` would otherwise re-target the request
+    # at a different route. `erb` is a default gem on every supported Ruby, so this costs no
+    # dependency.
+    #
+    # @param value [String] the identifier to interpolate.
+    # @return [String] the percent-encoded segment.
+    def self.escape_segment(value) = ERB::Util.url_encode(value)
+
+    # @param attachments [Array<Attachment>, nil] the attachments as supplied.
+    # @return [Array<Hash>, nil] JSON-serializable attachments, or nil when there are none.
+    def self.encode_attachments(attachments)
+      return nil if attachments.nil? || attachments.empty?
+
+      attachments.map do |item|
+        # `[bytes].pack("m0")` rather than `Base64.strict_encode64`: `base64` is a bundled gem from
+        # Ruby 3.4, so requiring it without declaring it fails under Bundler, and declaring it would
+        # cost this gem its zero-dependency claim.
+        entry = { "filename" => item.filename, "content" => [item.content].pack("m0") }
+        entry["content_type"] = item.content_type unless item.content_type.nil?
+        entry
+      end
+    end
+
+    # @param tags [Array<Tag>, nil] the tags as supplied.
+    # @return [Array<Hash>, nil] JSON-serializable tags, or nil when there are none.
+    def self.encode_tags(tags)
+      return nil if tags.nil? || tags.empty?
+
+      tags.map { |tag| { "name" => tag.name, "value" => tag.value } }
+    end
+  end
+end