mailtea 0.2.0

data/lib/mailtea/inbound.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Mailtea
+  # Attachments on a received email. Reach it at
+  # <tt>mailtea.emails.inbound.attachments</tt>.
+  #
+  # Each returned object carries a short-lived signed +download_url+.
+  class InboundAttachments < Resource
+    BASE = "/v1/emails/inbound"
+
+    # List an inbound email's attachments, each with a signed download URL.
+    def list(id)
+      request("GET", BASE + "/" + escape(id) + "/attachments")
+    end
+
+    # Retrieve a single inbound attachment with a signed download URL.
+    def get(id, attachment_id)
+      request("GET", BASE + "/" + escape(id) + "/attachments/" + escape(attachment_id))
+    end
+  end
+
+  # Inbound (received) emails. Reach it at <tt>mailtea.emails.inbound</tt>.
+  #
+  # List and retrieve mail delivered to your receiving domains, download
+  # attachments, and #reply — which threads correctly by construction and reuses
+  # the transactional send pipeline. Scoped to a publication: pass
+  # +publication_id+ to #list.
+  class InboundEmails < Resource
+    BASE = "/v1/emails/inbound"
+
+    # Attachments on a received email.
+    attr_reader :attachments
+
+    def initialize(request)
+      super
+      @attachments = InboundAttachments.new(request)
+    end
+
+    # List received emails in a publication (most recent first), cursor-paginated.
+    # Takes +publication_id+, optional +limit+ (1-100, default 20) and +cursor+.
+    def list(params = nil, **filters)
+      request("GET", BASE + query(payload(params, filters)))
+    end
+
+    # Retrieve a single received email, including its body, headers, and attachments.
+    def get(id)
+      request("GET", BASE + "/" + escape(id))
+    end
+
+    # Reply to a received email. The reply target (+to+), the threading headers
+    # and the "Re: " subject default are all server-derived — pass only the
+    # content. Returns the resulting transactional email's +id+ and +status+.
+    def reply(id, params = nil, html: UNSET, text: UNSET, from: UNSET, subject: UNSET,
+              cc: UNSET, bcc: UNSET, idempotency_key: UNSET, **rest)
+      body = payload(
+        params,
+        { html: html, text: text, from: from, subject: subject,
+          cc: cc, bcc: bcc, idempotency_key: idempotency_key },
+        rest
+      )
+      request("POST", BASE + "/" + escape(id) + "/reply", body)
+    end
+  end
+end

data/lib/mailtea/posts.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Mailtea
+  # The +posts+ resource (newsletter posts/issues). Reach it at
+  # <tt>mailtea.posts</tt>.
+  class Posts < Resource
+    # Create a newsletter post (a draft by default). Seed it from a published
+    # server template with +template_id+ + +variables+, or pass inline +html+.
+    # +kind+ selects the post type ("newsletter" or "broadcast"). Set
+    # <tt>send: true</tt> to deliver right after creating (or with
+    # +scheduled_at+ to schedule) — that requires the +issues:send+ scope.
+    #
+    # Returns <tt>{ "id" => ... }</tt>.
+    def create(params = nil, publication_id: UNSET, subject: UNSET, html: UNSET,
+               text: UNSET, template_id: UNSET, variables: UNSET, from: UNSET,
+               reply_to: UNSET, name: UNSET, kind: UNSET, send: UNSET,
+               scheduled_at: UNSET, **rest)
+      body = payload(
+        params,
+        { publication_id: publication_id, subject: subject, html: html, text: text,
+          template_id: template_id, variables: variables, from: from,
+          reply_to: reply_to, name: name, kind: kind, send: send,
+          scheduled_at: scheduled_at },
+        rest
+      )
+      request("POST", "/v1/posts", body)
+    end
+
+    # List posts (most recent first, offset-paginated). Takes +publication_id+
+    # (required) plus optional +limit+, +offset+, +status+ and +kind+
+    # ("newsletter" or "broadcast"). Returns <tt>{ "data", "total" }</tt>.
+    def list(params = nil, **filters)
+      request("GET", "/v1/posts" + query(payload(params, filters)))
+    end
+
+    # Retrieve a post by id.
+    def get(id, params = nil, **filters)
+      request("GET", "/v1/posts/" + escape(id) + query(payload(params, filters)))
+    end
+
+    # Update a draft post (sent posts are immutable). Accepts +subject+, +html+,
+    # +text+, +from+, +reply_to+ and +name+.
+    def update(id, params = nil, **fields)
+      request("PATCH", "/v1/posts/" + escape(id), payload(params, fields))
+    end
+
+    # Delete a draft post (sent posts cannot be deleted).
+    def delete(id, params = nil, **filters)
+      request("DELETE", "/v1/posts/" + escape(id) + query(payload(params, filters)))
+    end
+
+    # Send a draft post to the publication's audience — immediately, or at
+    # +scheduled_at+ (ISO 8601) if given. Requires the +issues:send+ scope.
+    #
+    # Like Emails#send this shadows Object#send on the resource object;
+    # +__send__+ is untouched.
+    def send(id, params = nil, scheduled_at: UNSET, **rest)
+      body = payload(params, { scheduled_at: scheduled_at }, rest)
+      # An empty body would fail the schema's parse of "{}" on some proxies and
+      # says nothing anyway, so an unscheduled send goes out with no body at all.
+      request("POST", "/v1/posts/" + escape(id) + "/send", body.empty? ? nil : body)
+    end
+
+    # Send a TEST copy of a post to specific recipients to check it before
+    # subscribers see it. Renders the post exactly as a subscriber would receive
+    # it and delivers a one-shot "[TEST]" email — it does NOT send to the audience.
+    #
+    # Takes +recipients+ (up to 10), +from+ (must use a verified domain) and
+    # optional +reply_to+. Returns <tt>{ "sent_to" => [...], "failed_to" => [...] }</tt>.
+    def send_test(id, params = nil, recipients: UNSET, from: UNSET, reply_to: UNSET, **rest)
+      body = payload(params, { recipients: recipients, from: from, reply_to: reply_to }, rest)
+      request("POST", "/v1/posts/" + escape(id) + "/test", body)
+    end
+  end
+end

data/lib/mailtea/resource.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "error"
+require_relative "util"
+
+module Mailtea
+  # Base class for the resource objects hanging off Mailtea::Client. It holds
+  # the client's request callable; everything else lives in the subclasses.
+  class Resource
+    def initialize(request)
+      @request = request
+    end
+
+    private
+
+    # +raw+ hands back the response body as text instead of parsed JSON, for the
+    # handful of endpoints that answer with something other than JSON.
+    def request(method, path, body = nil, raw: false)
+      @request.call(method, path, body, raw: raw)
+    end
+
+    def payload(*sources)
+      Util.payload(*sources)
+    end
+
+    def query(params)
+      Util.query(params)
+    end
+
+    def escape(value)
+      Util.escape(value)
+    end
+  end
+end

data/lib/mailtea/response.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Mailtea
+  # An API response: the parsed JSON, as a Hash that accepts Symbol keys too.
+  #
+  #   email["id"]   # => "txemail_..."
+  #   email[:id]    # => "txemail_..."
+  #
+  # Keys are the wire names exactly as the API sends them (snake_case strings) —
+  # nothing is renamed on the way in, so what the API reference documents is what
+  # you index. Symbol access exists because a Ruby caller writing +email[:id]+
+  # right after writing +send(to:, subject:)+ should not get +nil+.
+  #
+  # +[]+, +[]=+, +fetch+, +key?+, +dig+ and +delete+ all normalize. Hash's bulk
+  # mutators (+merge+, +merge!+, +update+) are C-implemented and do not route
+  # through +[]=+, so a Symbol key added that way stays a Symbol — merge into a
+  # plain Hash if you need that, rather than into a response.
+  class Response < Hash
+    def [](key)
+      super(normalize(key))
+    end
+
+    def fetch(key, *args, &block)
+      super(normalize(key), *args, &block)
+    end
+
+    def key?(key)
+      super(normalize(key))
+    end
+    alias has_key? key?
+    alias include? key?
+    alias member? key?
+
+    # Writes normalize too, or the class keeps only half its promise: a caller
+    # who sets email[:status] and reads email[:status] back would get nil,
+    # because the read side went looking for "status". (The JSON parser builds
+    # these through []= with String keys, where normalize is a no-op.)
+    def []=(key, value)
+      super(normalize(key), value)
+    end
+    alias store []=
+
+    def delete(key, &block)
+      super(normalize(key), &block)
+    end
+
+    # Hash#dig is C-implemented and would not route through the [] above, so a
+    # nested lookup with symbols needs its own walk.
+    def dig(key, *rest)
+      value = self[key]
+      return value if rest.empty? || value.nil?
+
+      value.dig(*rest)
+    end
+
+    private
+
+    def normalize(key)
+      key.is_a?(Symbol) ? key.to_s : key
+    end
+  end
+end

data/lib/mailtea/segments.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Mailtea
+  # The +segments+ resource. Reach it at <tt>mailtea.segments</tt>.
+  #
+  # Audience segments are scoped to a publication — pass +publication_id+. To
+  # clear a nullable filter on update pass +nil+ (e.g. <tt>status_filter: nil</tt>);
+  # omit the keyword to leave it unchanged.
+  class Segments < Resource
+    # Create a segment. Takes +publication_id+ and +name+, plus optional
+    # +description+, +status_filter+ and +query_filter+.
+    def create(params = nil, **fields)
+      request("POST", "/v1/segments", payload(params, fields))
+    end
+
+    # List segments. Filters: +publication_id+ (required), +limit+, +after+.
+    def list(params = nil, **filters)
+      request("GET", "/v1/segments" + query(payload(params, filters)))
+    end
+
+    # Retrieve a segment. Requires +publication_id+.
+    def get(id, params = nil, **filters)
+      request("GET", "/v1/segments/" + escape(id) + query(payload(params, filters)))
+    end
+
+    # Update a segment's +name+, +description+, +status_filter+ or
+    # +query_filter+. +publication_id+ is required and goes in the query string.
+    def update(id, params = nil, **fields)
+      scope, body = Util.split_publication(payload(params, fields))
+      request("PATCH", "/v1/segments/" + escape(id) + scope, body)
+    end
+
+    # Delete a segment. Requires +publication_id+.
+    def delete(id, params = nil, **filters)
+      request("DELETE", "/v1/segments/" + escape(id) + query(payload(params, filters)))
+    end
+  end
+end

data/lib/mailtea/senders.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Mailtea
+  # The +senders+ resource (named From identities). Reach it at
+  # <tt>mailtea.senders</tt>.
+  #
+  # Senders are scoped to a publication — pass +publication_id+. #create takes
+  # +name+ and +email+ (the address must live on a verified, DKIM-verified email
+  # domain), plus optional +reply_to+ and +is_default+. The +email+ is
+  # immutable, so #update only changes +name+, +reply_to+ and +is_default+.
+  class Senders < Resource
+    def create(params = nil, **fields)
+      request("POST", "/v1/senders", payload(params, fields))
+    end
+
+    # List senders (cursor-paginated). Filters: +publication_id+ (required),
+    # +limit+, +after+ (cursor from a previous +next_cursor+).
+    def list(params = nil, **filters)
+      request("GET", "/v1/senders" + query(payload(params, filters)))
+    end
+
+    # Retrieve a sender. Requires +publication_id+.
+    def get(id, params = nil, **filters)
+      request("GET", "/v1/senders/" + escape(id) + query(payload(params, filters)))
+    end
+
+    # Update a sender's +name+, +reply_to+ or +is_default+ (the +email+ is
+    # immutable). +publication_id+ is required, in the body.
+    def update(id, params = nil, **fields)
+      request("PATCH", "/v1/senders/" + escape(id), payload(params, fields))
+    end
+
+    # Delete a sender. Requires +publication_id+.
+    def delete(id, params = nil, **filters)
+      request("DELETE", "/v1/senders/" + escape(id) + query(payload(params, filters)))
+    end
+  end
+end

data/lib/mailtea/suppressions.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Mailtea
+  # The +suppressions+ resource (the org-wide do-not-send list). Reach it at
+  # <tt>mailtea.suppressions</tt>.
+  #
+  # Suppressions are team-scoped — there is no +publication_id+.
+  class Suppressions < Resource
+    # List suppression entries (cursor-paginated). Optional filters: +reason+,
+    # +q+ (email search), +created_after+, +created_before+, +limit+,
+    # +starting_after+ (cursor from a previous +next_cursor+).
+    def list(params = nil, **filters)
+      request("GET", "/v1/suppressions" + query(payload(params, filters)))
+    end
+
+    # Add addresses to the suppression list. Takes +emails+ (an Array, up to
+    # 1000) and an optional +reason+. Returns <tt>{ "added" => ... }</tt>.
+    def add(params = nil, **fields)
+      request("POST", "/v1/suppressions", payload(params, fields))
+    end
+
+    # Remove addresses from the suppression list. Takes +emails+ (an Array).
+    # Returns <tt>{ "removed" => ... }</tt>.
+    def remove(params = nil, **fields)
+      request("DELETE", "/v1/suppressions", payload(params, fields))
+    end
+
+    # Export the whole suppression list as CSV. Returns the raw text/csv body
+    # ("email,reason,source,created_at" with a header row) as a String, not a
+    # parsed response.
+    def export
+      request("GET", "/v1/suppressions/export", nil, raw: true)
+    end
+  end
+end

data/lib/mailtea/templates.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Mailtea
+  # The +templates+ resource (reusable server-side email templates). Reach it at
+  # <tt>mailtea.templates</tt>.
+  #
+  # Templates are scoped to a publication — pass +publication_id+ (except
+  # #render, which just renders a spec). Create one from raw +html+, a
+  # json-render +spec+, or an +editor_doc+ (a Studio editor design), then
+  # #publish it before seeding posts/emails from it.
+  class Templates < Resource
+    # Render a json-render +spec+ (with optional +variables+) to HTML without
+    # creating a template. Returns <tt>{ "html" => ..., "text" => ... }</tt>.
+    def render(params = nil, **fields)
+      request("POST", "/v1/templates/render", payload(params, fields))
+    end
+
+    # Create a template from +html+, a +spec+, OR an +editor_doc+ (exactly one
+    # is required — the server renders +html+ from an +editor_doc+, so do not
+    # send both). Takes +publication_id+ and +name+, plus optional
+    # +style_profile+, +mailtea_theme+, +global_css+, +category+,
+    # +preview_image_url+, +tags+, +description+, +text+, +subject+, +from+,
+    # +reply_to+ and +variables+.
+    def create(params = nil, **fields)
+      request("POST", "/v1/templates", payload(params, fields))
+    end
+
+    # List templates (cursor-paginated). Filters: +publication_id+ (required),
+    # +limit+, +after+ (cursor from a previous +next_cursor+).
+    def list(params = nil, **filters)
+      request("GET", "/v1/templates" + query(payload(params, filters)))
+    end
+
+    # Retrieve a template. Requires +publication_id+.
+    def get(id, params = nil, **filters)
+      request("GET", "/v1/templates/" + escape(id) + query(payload(params, filters)))
+    end
+
+    # Update a template's +name+, +html+/+spec+/+editor_doc+, +style_profile+,
+    # +mailtea_theme+, +global_css+, +category+, +preview_image_url+, +tags+,
+    # +description+, +text+, +subject+, +from+, +reply_to+ or +variables+. An
+    # +editor_doc+ re-renders +html+ server-side, so do not send both.
+    #
+    # +global_css+, +category+, +preview_image_url+, +tags+, +text+, +subject+,
+    # +from+ and +reply_to+ accept +nil+ to clear them. +publication_id+ is
+    # required and goes in the query string.
+    def update(id, params = nil, **fields)
+      scope, body = Util.split_publication(payload(params, fields))
+      request("PATCH", "/v1/templates/" + escape(id) + scope, body)
+    end
+
+    # Publish a template so it can seed posts/emails. Requires +publication_id+.
+    def publish(id, params = nil, **filters)
+      request("POST", "/v1/templates/" + escape(id) + "/publish" + query(payload(params, filters)))
+    end
+
+    # Return a published template to draft. +published_at+ is kept — it records
+    # that the template was published once, not that it still is. Requires
+    # +publication_id+.
+    def unpublish(id, params = nil, **filters)
+      request("POST", "/v1/templates/" + escape(id) + "/unpublish" + query(payload(params, filters)))
+    end
+
+    # List a template's design history, newest first. Requires +publication_id+;
+    # optional +limit+ (the server caps it at the retained maximum).
+    #
+    # Entries are metadata only — +version+, +origin+ ("edit", "publish" or
+    # "restore"), +restored_from_version+, +format+, +name+, +sealed+,
+    # +is_current+, +created_at+, +updated_at+ and +author+ (or nil) — never the
+    # design document, which one entry alone can carry half a megabyte of.
+    # +is_current+ marks the design the template is serving right now, which is
+    # not always the newest entry: a metadata-only update touches the template
+    # without recording a version.
+    #
+    # The reply also carries +retention+: only the newest +max_versions+ are
+    # kept, and consecutive edits by the same author within
+    # +coalesce_window_seconds+ collapse into one entry.
+    def versions(id, params = nil, **filters)
+      request("GET", "/v1/templates/" + escape(id) + "/versions" + query(payload(params, filters)))
+    end
+
+    # Put an older design from #versions back onto the template. Requires
+    # +publication_id+.
+    #
+    # *Restoring is a content write, so the template returns to draft* —
+    # automations and the API stop sending it until #publish is called again.
+    # The reply's +unpublished+ reports whether that just happened; re-publishing
+    # is the caller's job.
+    #
+    # History is forward-only: the design being replaced is recorded as its own
+    # version first, then the restored design is appended as the new newest one.
+    # Nothing is rewound or deleted, so a restore is itself undone by restoring
+    # the entry directly above it.
+    #
+    # Restoring the design that is already current writes nothing and returns
+    # <tt>restored: false</tt> with <tt>reason: "identical"</tt> and
+    # <tt>unpublished: false</tt>, so a no-op restore cannot unpublish a live
+    # template. A version that has aged out of retention raises Mailtea::Error
+    # with +code+ "template_version_not_found". Returns +restored+,
+    # +restored_from_version+, +unpublished+, +message+ and the updated +template+.
+    def restore_version(id, version, params = nil, **filters)
+      request(
+        "POST",
+        "/v1/templates/" + escape(id) + "/versions/" + escape(version) + "/restore" +
+          query(payload(params, filters))
+      )
+    end
+
+    # Duplicate a template into a new draft. Requires +publication_id+.
+    def duplicate(id, params = nil, **filters)
+      request("POST", "/v1/templates/" + escape(id) + "/duplicate" + query(payload(params, filters)))
+    end
+
+    # Delete a template. Requires +publication_id+.
+    def delete(id, params = nil, **filters)
+      request("DELETE", "/v1/templates/" + escape(id) + query(payload(params, filters)))
+    end
+  end
+end

data/lib/mailtea/topics.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Mailtea
+  # The +topics+ resource (topic definitions). Reach it at <tt>mailtea.topics</tt>.
+  #
+  # Topics are scoped to a publication — pass +publication_id+. This manages
+  # topic definitions only; assigning topics to contacts is not yet exposed.
+  class Topics < Resource
+    # Create a topic definition. Requires +publication_id+, +name+ and
+    # +default_subscription+ ("opt_in" or "opt_out"). Optional +description+ and
+    # +visibility+ ("private" by default; "public" makes the topic appear on the
+    # reader preference page as its own subscription).
+    def create(params = nil, publication_id: UNSET, name: UNSET,
+               default_subscription: UNSET, description: UNSET, visibility: UNSET, **rest)
+      body = payload(
+        params,
+        { publication_id: publication_id, name: name,
+          default_subscription: default_subscription, description: description,
+          visibility: visibility },
+        rest
+      )
+      request("POST", "/v1/topics", body)
+    end
+
+    # List topic definitions. Filters: +publication_id+ (required), +limit+, +after+.
+    def list(params = nil, **filters)
+      request("GET", "/v1/topics" + query(payload(params, filters)))
+    end
+
+    # Retrieve a topic definition. Requires +publication_id+.
+    def get(id, params = nil, **filters)
+      request("GET", "/v1/topics/" + escape(id) + query(payload(params, filters)))
+    end
+
+    # Update a topic's +name+, +description+, +default_subscription+ or
+    # +visibility+. +publication_id+ is required and goes in the query string.
+    def update(id, params = nil, **fields)
+      scope, body = Util.split_publication(payload(params, fields))
+      request("PATCH", "/v1/topics/" + escape(id) + scope, body)
+    end
+
+    # Delete a topic definition. Requires +publication_id+.
+    def delete(id, params = nil, **filters)
+      request("DELETE", "/v1/topics/" + escape(id) + query(payload(params, filters)))
+    end
+  end
+end

data/lib/mailtea/transport.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
+
+require_relative "error"
+
+module Mailtea
+  # What a transport hands back: the HTTP status, the response headers with
+  # lowercased names, and the body as an undecoded String.
+  HttpResponse = Struct.new(:status, :headers, :body, keyword_init: true)
+
+  # The default HTTP transport: +net/http+ and +json+ from the standard library,
+  # no gems.
+  #
+  # A transport is anything that responds to
+  # <tt>call(method, url, headers, body) -> HttpResponse</tt>. Pass your own to
+  # <tt>Mailtea::Client.new(..., transport:)</tt> to record requests in tests, to
+  # route through a proxy or an instrumented HTTP stack, or to reuse a connection
+  # pool. Everything the client does above the wire — auth header, JSON encoding,
+  # error mapping — stays the same.
+  module Transport
+    VERBS = {
+      "GET" => Net::HTTP::Get,
+      "POST" => Net::HTTP::Post,
+      "PATCH" => Net::HTTP::Patch,
+      "DELETE" => Net::HTTP::Delete
+    }.freeze
+
+    OPEN_TIMEOUT_SECONDS = 10
+    READ_TIMEOUT_SECONDS = 30
+
+    module_function
+
+    def call(method, url, headers, body)
+      uri = parse_url(url)
+      request_class = VERBS.fetch(method) do
+        raise Error.new("Unsupported HTTP method #{method}", code: "unsupported_method")
+      end
+
+      request = request_class.new(uri)
+      headers.each { |name, value| request[name] = value }
+      # Net::HTTP::Delete has no request body by convention, but the API's
+      # suppressions removal takes one, and setting it here still sends it.
+      request.body = body if body
+      # A bodyless POST (cancel, publish, verify, activate…) is given an empty
+      # body by Net::HTTP, which then labels it application/x-www-form-urlencoded
+      # — a lie about a JSON API, and a warning under -w. Say what this client
+      # actually speaks instead.
+      if body.nil? && request.request_body_permitted?
+        request["Content-Type"] ||= "application/json"
+      end
+
+      response = Net::HTTP.start(
+        uri.hostname,
+        uri.port,
+        use_ssl: uri.scheme == "https",
+        open_timeout: OPEN_TIMEOUT_SECONDS,
+        read_timeout: READ_TIMEOUT_SECONDS
+      ) { |http| http.request(request) }
+
+      HttpResponse.new(
+        status: response.code.to_i,
+        headers: lowercased(response),
+        body: response.body.to_s
+      )
+    rescue Timeout::Error, SystemCallError, SocketError, IOError, OpenSSL::SSL::SSLError,
+           URI::InvalidURIError => e
+      # A request that never lands is as much a failed send as a 500, and the
+      # caller should only have to rescue one class. status 0 says it never
+      # reached the API.
+      # parse_url guarantees a URI::HTTP by here, so host and port are known.
+      raise Error.new(
+        "Could not reach Mailtea at #{uri.scheme}://#{uri.host}:#{uri.port}: " \
+        "#{e.class}: #{e.message}",
+        code: "connection_error"
+      )
+    end
+
+    # A base URL that is not http(s) is a configuration mistake, not a network
+    # fault, and it has to arrive as Mailtea::Error like every other failure —
+    # the whole point of the one-rescue contract is that nothing else escapes.
+    # Left alone, the two ways to get it wrong both break that: Net::HTTP.start
+    # answers "api.mailtea.app" (no scheme) with a bare ArgumentError, and
+    # URI.parse answers "127.0.0.1:7787" — the classic MAILTEA_API_BASE_URL
+    # typo, since a host:port reads as scheme:opaque — with InvalidURIError.
+    def parse_url(url)
+      uri = URI.parse(url)
+      return uri if uri.is_a?(URI::HTTP) # URI::HTTPS is a subclass
+
+      raise invalid_base_url(url)
+    rescue URI::InvalidURIError
+      raise invalid_base_url(url)
+    end
+
+    def invalid_base_url(url)
+      # Report the base rather than the whole URL: every path this client builds
+      # starts at "/v1", so the split leaves exactly the configured part — and
+      # keeps recipient addresses out of the message when the query held one.
+      Error.new(
+        "Mailtea's base URL must be an http:// or https:// URL — got " \
+        "#{url.split("/v1", 2).first.inspect}. Check MAILTEA_API_BASE_URL, or the " \
+        "base_url: passed to Mailtea::Client.new.",
+        code: "invalid_base_url"
+      )
+    end
+
+    def lowercased(response)
+      headers = {}
+      response.each_header { |name, value| headers[name.downcase] = value }
+      headers
+    end
+  end
+end