mailtea 0.2.0

data/lib/mailtea/util.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Mailtea
+  # Sentinel for "this keyword was not given".
+  #
+  # It exists because +nil+ already means something on the wire: the API clears a
+  # nullable field when it receives an explicit JSON +null+, and leaves it alone
+  # when the key is absent. A keyword defaulting to +nil+ would collapse those
+  # two, so every optional keyword defaults to UNSET and is dropped from the
+  # payload; pass +nil+ deliberately and it is sent as +null+.
+  #
+  #   mailtea.segments.update(id, publication_id: pub)                     # leaves the filter alone
+  #   mailtea.segments.update(id, publication_id: pub, status_filter: nil) # clears it
+  UNSET = Object.new
+  def UNSET.inspect
+    "Mailtea::UNSET"
+  end
+  UNSET.freeze
+
+  # Internal helpers shared by the resource classes. Not part of the public API.
+  module Util
+    module_function
+
+    # Merge a wire-format Hash with keyword arguments into one payload.
+    #
+    # Sources are applied left to right, so keywords win over the Hash — the same
+    # precedence the Python SDK uses. Keys are stringified, so
+    # <tt>send({"from" => a}, from: b)</tt> is one key, not two.
+    def payload(*sources)
+      merged = {}
+      sources.each do |source|
+        next if source.nil?
+
+        source.each do |key, value|
+          next if value.equal?(UNSET)
+
+          merged[key.to_s] = value
+        end
+      end
+      merged
+    end
+
+    # Render "?a=1&b=2" from a Hash, dropping nil and UNSET values.
+    #
+    # Returns "" for an empty result so it can be appended to a path
+    # unconditionally. Array values become repeated keys (+a=1&a=2+); booleans
+    # render as +true+/+false+, which is what the API's query parsers read.
+    def query(params)
+      return "" if params.nil? || params.empty?
+
+      pairs = params.each_with_object([]) do |(key, value), acc|
+        next if value.nil? || value.equal?(UNSET)
+
+        acc << [key.to_s, value]
+      end
+      pairs.empty? ? "" : "?#{URI.encode_www_form(pairs)}"
+    end
+
+    # Percent-encode one path segment. Every reserved character is escaped
+    # (including "/"), so an id containing a slash cannot walk to another route.
+    def escape(value)
+      value.to_s.gsub(/[^A-Za-z0-9\-._~]/) do |char|
+        char.bytes.map { |byte| format("%%%02X", byte) }.join
+      end
+    end
+
+    # Split a payload into the publication_id that several endpoints want in the
+    # query string and the rest of the body. Returns [query_string, body].
+    def split_publication(merged, keep_in_body: true)
+      publication_id = merged["publication_id"]
+      body = keep_in_body ? merged : merged.reject { |key, _| key == "publication_id" }
+      [query({ "publication_id" => publication_id }), body]
+    end
+  end
+end

data/lib/mailtea/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Mailtea
+  VERSION = "0.2.0"
+end

data/lib/mailtea/webhook_signing.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+# Standard Webhooks (standardwebhooks.com) signature verification.
+#
+# A stdlib-only mirror of the Mailtea signer, kept in exact parity so a signature
+# produced by the platform verifies here byte-for-byte.
+#
+# The stored signing secret is <tt>whsec_<base64></tt>; the HMAC key is the
+# base64 remainder decoded to bytes. The signed content is
+# <tt>{msg_id}.{timestamp}.{payload}</tt> where +timestamp+ is Unix SECONDS,
+# matching the +webhook-timestamp+ header. The +webhook-signature+ header is
+# <tt>v1,<base64 HMAC-SHA256></tt>; during key rotation it may carry several
+# space-delimited <tt>v1,<sig></tt> tokens and a match against any one of them
+# passes.
+module Mailtea
+  SECRET_PREFIX = "whsec_"
+  SIGNATURE_VERSION = "v1"
+  DEFAULT_TOLERANCE_SECONDS = 300
+
+  module_function
+
+  # Sign a webhook payload.
+  #
+  # Returns the +webhook-signature+ header value in Standard Webhooks form,
+  # <tt>v1,<base64 HMAC-SHA256></tt>. Useful for faking Mailtea deliveries in
+  # tests.
+  #
+  # +timestamp+ is Unix seconds — the same value sent in +webhook-timestamp+.
+  def sign_webhook(secret, msg_id, timestamp, payload)
+    "#{SIGNATURE_VERSION},#{compute_signature(secret, msg_id, timestamp.to_i, payload)}"
+  end
+
+  # Verify a +webhook-signature+ header against the expected HMAC.
+  #
+  # The header may carry multiple space-delimited <tt>v1,<sig></tt> tokens
+  # (Standard Webhooks allows key rotation — the platform may sign a delivery
+  # with both the old and new secret); a match against any +v1+ token passes.
+  #
+  # Returns false when the timestamp is outside +tolerance_seconds+ of +now+
+  # (replay protection). Uses a constant-time comparison. Never raises on a bad
+  # signature — it returns false.
+  #
+  # [secret]           the endpoint's signing secret (+whsec_...+).
+  # [msg_id]           the +webhook-id+ header value.
+  # [timestamp]        the +webhook-timestamp+ header value (Unix seconds; the
+  #                    String the header arrives as is accepted and coerced).
+  # [payload]          the raw request body, exactly as received.
+  # [signature_header] the +webhook-signature+ header value.
+  # [tolerance_seconds] allowed clock skew each way. Default 5 minutes.
+  # [now]              injectable current time (Unix seconds) for tests.
+  #
+  #   ok = Mailtea.verify_webhook_signature(
+  #     signing_secret,
+  #     request.headers["webhook-id"],
+  #     request.headers["webhook-timestamp"],
+  #     request.raw_post,
+  #     request.headers["webhook-signature"]
+  #   )
+  def verify_webhook_signature(secret, msg_id, timestamp, payload, signature_header,
+                               tolerance_seconds: DEFAULT_TOLERANCE_SECONDS, now: nil)
+    timestamp_seconds = coerce_timestamp(timestamp)
+    return false if timestamp_seconds.nil?
+
+    now_seconds = (now.nil? ? Time.now.to_i : now.to_i)
+    return false if (now_seconds - timestamp_seconds).abs > tolerance_seconds
+
+    expected = compute_signature(secret, msg_id, timestamp_seconds, payload)
+
+    signature_header.to_s.split(" ").any? do |token|
+      version, _, signature = token.partition(",")
+      # OpenSSL's comparison is length-safe and constant-time; == on Strings is
+      # neither, and a byte-by-byte early exit is a timing oracle on the digest.
+      version == SIGNATURE_VERSION &&
+        !signature.empty? &&
+        OpenSSL.secure_compare(signature, expected)
+    end
+  end
+
+  # Decode the HMAC key from a +whsec_+-prefixed secret.
+  #
+  # Matches Node's lenient base64 decoder: accepts the base64url alphabet and
+  # tolerates missing padding, so a secret minted with either alphabet decodes to
+  # the same bytes.
+  def decode_signing_key(secret)
+    raw = secret.start_with?(SECRET_PREFIX) ? secret[SECRET_PREFIX.length..] : secret
+    raw = raw.strip.tr("-_", "+/")
+    raw += "=" * ((4 - (raw.length % 4)) % 4)
+    raw.unpack1("m")
+  end
+
+  def compute_signature(secret, msg_id, timestamp, payload)
+    signed_content = "#{msg_id}.#{timestamp}.#{payload}"
+    digest = OpenSSL::HMAC.digest("SHA256", decode_signing_key(secret), signed_content)
+    [digest].pack("m0")
+  end
+
+  # A header value is a String, and String#to_i turns "abc" into 0 — which would
+  # be inside no tolerance window but is still a value, so the parse has to fail
+  # loudly rather than round to the epoch.
+  def coerce_timestamp(timestamp)
+    return timestamp.floor if timestamp.is_a?(Integer)
+    return nil if timestamp.is_a?(Float) && !timestamp.finite?
+    return timestamp.floor if timestamp.is_a?(Numeric)
+
+    Float(timestamp.to_s).floor
+  rescue ArgumentError, TypeError, FloatDomainError
+    nil
+  end
+
+  private_class_method :decode_signing_key, :compute_signature, :coerce_timestamp
+end

data/lib/mailtea/webhooks.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Mailtea
+  # The +webhooks+ resource (outbound event subscriptions). Reach it at
+  # <tt>mailtea.webhooks</tt>.
+  #
+  # Scoped to a publication — pass +publication_id+. #create returns the
+  # +signing_secret+ once; store it and verify deliveries with
+  # Mailtea.verify_webhook_signature.
+  class Webhooks < Resource
+    BASE = "/v1/webhooks/endpoints"
+
+    # Create an endpoint. Takes +publication_id+, +url+ and +events+.
+    def create(params = nil, **fields)
+      request("POST", BASE, payload(params, fields))
+    end
+
+    # List endpoints. Requires +publication_id+.
+    def list(params = nil, **filters)
+      request("GET", BASE + query(payload(params, filters)))
+    end
+
+    # Retrieve an endpoint. Requires +publication_id+.
+    def get(id, params = nil, **filters)
+      request("GET", BASE + "/" + escape(id) + query(payload(params, filters)))
+    end
+
+    # Update an endpoint's +url+, +events+ or +enabled+. +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", BASE + "/" + escape(id) + scope, body)
+    end
+
+    # Delete an endpoint. Requires +publication_id+.
+    def delete(id, params = nil, **filters)
+      request("DELETE", BASE + "/" + escape(id) + query(payload(params, filters)))
+    end
+  end
+end

data/lib/mailtea.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# The official Ruby SDK for Mailtea — send, schedule, and manage email from your
+# app or AI agent.
+#
+#   require "mailtea"
+#
+#   mailtea = Mailtea::Client.new
+#   mailtea.emails.send(
+#     from: "you@yourdomain.com",
+#     to: "recipient@example.com",
+#     subject: "Hello from Mailtea",
+#     html: "<p>Your first email, sent with Mailtea.</p>"
+#   )
+#
+# See Mailtea::Client for the resources, Mailtea::Error for what a failure
+# carries, and Mailtea.verify_webhook_signature for inbound webhooks.
+module Mailtea
+end
+
+require_relative "mailtea/version"
+require_relative "mailtea/error"
+require_relative "mailtea/response"
+require_relative "mailtea/client"
+require_relative "mailtea/webhook_signing"

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: mailtea
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Mailtea
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-06 00:00:00.000000000 Z
+dependencies: []
+description: 'The official Ruby SDK for Mailtea: a thin, zero-dependency wrapper over
+  the Mailtea REST API, built on net/http and json.'
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/mailtea.rb
+- lib/mailtea/api_keys.rb
+- lib/mailtea/assets.rb
+- lib/mailtea/automation_runs.rb
+- lib/mailtea/automations.rb
+- lib/mailtea/client.rb
+- lib/mailtea/contact_properties.rb
+- lib/mailtea/contacts.rb
+- lib/mailtea/domains.rb
+- lib/mailtea/emails.rb
+- lib/mailtea/error.rb
+- lib/mailtea/events.rb
+- lib/mailtea/inbound.rb
+- lib/mailtea/posts.rb
+- lib/mailtea/resource.rb
+- lib/mailtea/response.rb
+- lib/mailtea/segments.rb
+- lib/mailtea/senders.rb
+- lib/mailtea/suppressions.rb
+- lib/mailtea/templates.rb
+- lib/mailtea/topics.rb
+- lib/mailtea/transport.rb
+- lib/mailtea/util.rb
+- lib/mailtea/version.rb
+- lib/mailtea/webhook_signing.rb
+- lib/mailtea/webhooks.rb
+homepage: https://mailtea.app
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://mailtea.app
+  documentation_uri: https://docs.mailtea.app
+  source_code_uri: https://github.com/mailtea-app/mailtea-ruby
+  changelog_uri: https://github.com/mailtea-app/mailtea-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/mailtea-app/mailtea-ruby/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Mailtea Ruby SDK — send, schedule, and manage email from your app or AI agent.
+test_files: []