sealpost 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6e2cc83834cb454f75aae9fa1a26c044897c746edd16c20455a2f343d1f5879d
+  data.tar.gz: a0673046f81e3b45f487bcee469f9ee9fd697fecb07322400f99743d4c75315c
+SHA512:
+  metadata.gz: bef36104217ee183302be9ccf58d03158fa36e3388c96a8115c06c09b5cebae0c8ba544bc3540c05c4a8a0ddb6b3ea179a6ffddf71f18624e47e85ee58fa7e55
+  data.tar.gz: 566aaef5ceeaa94e3386dbad81c05962c537d0cff3d97483b3b6f036c086052c307dde47e8d266f0a5bcf58797c38c9ff6d0ee9bef3accf7971c66f59624d5b9

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sagar Pinninti
+
+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,30 @@
+# sealpost (Ruby)
+
+Zero-dependency Ruby client for the self-hosted [Sealpost](https://github.com/isagarpinninti/sealpost) email API. Ruby 2.6+, standard library only.
+
+```bash
+gem install sealpost
+```
+
+```ruby
+require "sealpost"
+
+mail = Sealpost::Client.new(api_key: ENV["SEALPOST_KEY"], base_url: "https://mail.yourdomain.com")
+
+result = mail.emails.deliver(
+  template: "magic_link_otp_verification", to: "user@example.org",
+  variables: { userName: "Ada", otpCode: "482913", signInUrl: "https://app.example.com/in" },
+  idempotency_key: "signup-42", tags: [{ name: "campaign", value: "welcome" }],
+)
+if result.error&.code == "preflight_blocked"
+  puts result.error.preflight["checks"]   # nothing was sent
+elsif result.ok?
+  puts result.data["id"]
+end
+```
+
+Results are `Sealpost::Result` objects (`data` / `error`); nothing raises unless you call `.unwrap`. The method is `deliver` (alias `send_email`) because `send` is taken by Ruby's `Object`.
+
+Also: `emails.batch/get/list/preview`, `inbound.list/get/raw/attachment/delete`, `audiences.*`, `broadcasts.*`, `scheduled.*`, `suppressions.*`, `domains.list/check`, `stats`, `unsubscribe_link`, and `Sealpost::Webhooks.verify(secret, raw_body, header)`.
+
+Run the tests with `ruby test/sealpost_test.rb`. MIT.

data/lib/sealpost/client.rb

@@ -0,0 +1,297 @@
+module Sealpost
+  # One of data or error is set. Nothing raises unless you call #unwrap.
+  class Error
+    attr_reader :status, :code, :message, :preflight, :request_id
+
+    def initialize(status:, message:, code: nil, preflight: nil, request_id: nil)
+      @status = status # HTTP status, or 0 for a network failure or timeout
+      @message = message
+      @code = code
+      @preflight = preflight
+      @request_id = request_id
+    end
+
+    def to_s
+      "#{message} (#{status})#{code ? " [#{code}]" : ""}"
+    end
+  end
+
+  class SealpostException < StandardError
+    attr_reader :error
+
+    def initialize(error)
+      super(error.to_s)
+      @error = error
+    end
+  end
+
+  class Result
+    attr_reader :data, :error, :headers
+
+    def initialize(data: nil, error: nil, headers: {})
+      @data = data
+      @error = error
+      @headers = headers
+    end
+
+    def ok?
+      @error.nil?
+    end
+
+    # True when the server replayed an earlier response for the same idempotency_key.
+    def replayed?
+      @headers["idempotent-replayed"] == "true"
+    end
+
+    def unwrap
+      raise SealpostException, @error if @error
+      @data
+    end
+  end
+
+  class Resource
+    def initialize(client)
+      @c = client
+    end
+
+    private
+
+    def q(value)
+      URI.encode_www_form_component(value.to_s).gsub("+", "%20")
+    end
+
+    def query(params)
+      pairs = params.reject { |_, v| v.nil? }
+      pairs.empty? ? "" : "?" + URI.encode_www_form(pairs)
+    end
+  end
+
+  class Emails < Resource
+    WIRE = { auto_fill: "autoFill", include_mime: "includeMime", in_reply_to: "inReplyTo", scheduled_at: "scheduledAt" }.freeze
+
+    # Send one email. result.error.code == "preflight_blocked" means nothing was sent.
+    # Options: variables, domain, cc, bcc, auto_fill, attachments, tags, metadata, in_reply_to, scheduled_at (ISO 8601 or Time),
+    # idempotency_key (same key + body within 24 h returns the original result; see result.replayed?).
+    def deliver(template:, to:, idempotency_key: nil, **opts)
+      body = { "templateId" => template, "to" => to }
+      opts.each do |k, v|
+        next if v.nil?
+        v = v.utc.iso8601 if v.respond_to?(:utc) && k == :scheduled_at
+        body[WIRE.fetch(k, k.to_s)] = v
+      end
+      @c.request(:post, "/api/send", body, nil, idempotency_key ? { "Idempotency-Key" => idempotency_key } : {})
+    end
+    alias send_email deliver
+
+    def batch(items)
+      emails = items.map do |i|
+        i = i.dup
+        b = { "templateId" => i.delete(:template), "to" => i.delete(:to) }
+        i.each { |k, v| b[WIRE.fetch(k, k.to_s)] = v unless v.nil? }
+        b
+      end
+      @c.request(:post, "/api/send/batch", { "emails" => emails })
+    end
+
+    def preview(template:, to: [], **opts)
+      body = { "templateId" => template, "to" => to }
+      opts.each { |k, v| body[WIRE.fetch(k, k.to_s)] = v unless v.nil? }
+      @c.request(:post, "/api/compile", body)
+    end
+
+    def get(id)
+      @c.request(:get, "/api/emails/#{q(id)}")
+    end
+
+    # Newest first. Page with before: page["nextCursor"].
+    def list(status: nil, to: nil, template: nil, domain: nil, tag: nil, since: nil, until_: nil, limit: nil, before: nil)
+      @c.request(:get, "/api/emails" + query(status: status, to: to, template: template, domain: domain, tag: tag, since: since, until: until_, limit: limit, before: before))
+    end
+  end
+
+  class Inbound < Resource
+    # Received mail. html bodies are untrusted: show them only in a sandboxed frame with remote content blocked.
+    def list(from: nil, to: nil, q: nil, kind: nil, since: nil, until_: nil, limit: nil, before: nil)
+      @c.request(:get, "/api/inbound" + query(from: from, to: to, q: q, kind: kind, since: since, until: until_, limit: limit, before: before))
+    end
+
+    def get(id)
+      @c.request(:get, "/api/inbound/#{q(id)}")
+    end
+
+    def raw(id)
+      @c.request_bytes("/api/inbound/#{q(id)}/raw")
+    end
+
+    def attachment(id, index)
+      @c.request_bytes("/api/inbound/#{q(id)}/attachments/#{Integer(index)}")
+    end
+
+    def delete(id)
+      @c.request(:delete, "/api/inbound/#{q(id)}")
+    end
+  end
+
+  class Audiences < Resource
+    def create(name)
+      @c.request(:post, "/api/audiences", { "name" => name }, ->(j) { j["audience"] })
+    end
+
+    def list
+      @c.request(:get, "/api/audiences", nil, ->(j) { j["audiences"] || [] })
+    end
+
+    # contacts: [{ email:, name:, variables: {} }], up to 10,000 per call.
+    def add_contacts(id, contacts)
+      @c.request(:post, "/api/audiences/#{q(id)}/contacts", { "contacts" => contacts })
+    end
+
+    def delete(id)
+      @c.request(:delete, "/api/audiences/#{q(id)}")
+    end
+  end
+
+  class Broadcasts < Resource
+    def create(name:, audience_id:, template:, domain: nil, variables: nil, scheduled_at: nil, rate_per_minute: nil)
+      body = { "name" => name, "audienceId" => audience_id, "templateId" => template }
+      body["domain"] = domain if domain
+      body["variables"] = variables if variables
+      body["scheduledAtIso"] = scheduled_at.respond_to?(:utc) ? scheduled_at.utc.iso8601 : scheduled_at if scheduled_at
+      body["ratePerMinute"] = rate_per_minute if rate_per_minute
+      @c.request(:post, "/api/broadcasts", body, ->(j) { j["broadcast"] })
+    end
+
+    def list
+      @c.request(:get, "/api/broadcasts", nil, ->(j) { j["broadcasts"] || [] })
+    end
+
+    def get(id)
+      @c.request(:get, "/api/broadcasts/#{q(id)}")
+    end
+
+    def cancel(id)
+      @c.request(:post, "/api/broadcasts/#{q(id)}/cancel", {}, ->(j) { j["broadcast"] })
+    end
+  end
+
+  class Scheduled < Resource
+    def list
+      @c.request(:get, "/api/scheduled", nil, ->(j) { j["scheduled"] || [] })
+    end
+
+    def cancel(id)
+      @c.request(:delete, "/api/scheduled/#{q(id)}", nil, ->(j) { j["scheduled"] })
+    end
+  end
+
+  class Suppressions < Resource
+    def list
+      @c.request(:get, "/api/suppressions", nil, ->(j) { j["suppressions"] || [] })
+    end
+
+    def add(email, reason: "unsubscribed", detail: nil)
+      @c.request(:post, "/api/suppressions", { "email" => email, "reason" => reason, "detail" => detail }.compact, ->(j) { j["suppressions"] || [] })
+    end
+
+    def remove(email)
+      @c.request(:delete, "/api/suppressions?email=#{q(email)}", nil, ->(j) { j["suppressions"] || [] })
+    end
+  end
+
+  class Domains < Resource
+    def list
+      @c.request(:get, "/api/domains", nil, ->(j) { j["domains"] || [] })
+    end
+
+    # Live SPF / DKIM / DMARC lookup.
+    def check(domain)
+      @c.request(:get, "/api/domains/#{q(domain)}/check")
+    end
+  end
+
+  class Client
+    attr_reader :emails, :inbound, :audiences, :broadcasts, :scheduled, :suppressions, :domains
+
+    def initialize(api_key:, base_url: "http://127.0.0.1:4320", timeout: 30)
+      raise ArgumentError, "Sealpost: api_key is required" if api_key.nil? || api_key.empty?
+      @key = api_key
+      @base = base_url.sub(%r{/+\z}, "")
+      @timeout = timeout
+      @emails = Emails.new(self)
+      @inbound = Inbound.new(self)
+      @audiences = Audiences.new(self)
+      @broadcasts = Broadcasts.new(self)
+      @scheduled = Scheduled.new(self)
+      @suppressions = Suppressions.new(self)
+      @domains = Domains.new(self)
+    end
+
+    def stats
+      request(:get, "/api/stats")
+    end
+
+    # A hosted one-click unsubscribe URL (needs unsubscribe.hosted and a trackingBaseUrl on the server).
+    def unsubscribe_link(email, domain: nil)
+      request(:post, "/api/unsubscribe-link", { "email" => email, "domain" => domain }.compact, ->(j) { j["url"] })
+    end
+
+    def verify_receipt(token, inbox_id: nil)
+      request(:post, "/api/verify", { "token" => token, "inboxId" => inbox_id }.compact)
+    end
+
+    # JSON request. pick: optional lambda that extracts the data from the parsed body.
+    def request(method, path, body = nil, pick = nil, extra_headers = {})
+      res = perform(method, path, body ? JSON.generate(body) : nil, extra_headers)
+      parsed = parse(res.body)
+      headers = {}
+      res.each_header { |k, v| headers[k.downcase] = v }
+      unless res.code.to_i.between?(200, 299)
+        return Result.new(error: Error.new(status: res.code.to_i, message: (parsed["error"] || "HTTP #{res.code}").to_s, code: parsed["code"], preflight: parsed["preflight"], request_id: parsed["requestId"] || headers["x-request-id"]), headers: headers)
+      end
+      Result.new(data: pick ? pick.call(parsed) : parsed, headers: headers)
+    rescue Timeout::Error, SystemCallError, SocketError, OpenSSL::SSL::SSLError, EOFError, Net::OpenTimeout, Net::ReadTimeout => e
+      Result.new(error: Error.new(status: 0, message: e.message))
+    end
+
+    # Binary download: { bytes:, content_type:, filename: }.
+    def request_bytes(path)
+      res = perform(:get, path, nil, {})
+      unless res.code.to_i.between?(200, 299)
+        parsed = parse(res.body)
+        return Result.new(error: Error.new(status: res.code.to_i, message: (parsed["error"] || "HTTP #{res.code}").to_s, code: parsed["code"], request_id: parsed["requestId"] || res["x-request-id"]))
+      end
+      encoded = res["content-disposition"].to_s[/filename\*=UTF-8''([^;]+)/i, 1]
+      Result.new(data: { bytes: res.body, content_type: res["content-type"], filename: encoded && URI.decode_www_form_component(encoded) })
+    rescue Timeout::Error, SystemCallError, SocketError, OpenSSL::SSL::SSLError, EOFError, Net::OpenTimeout, Net::ReadTimeout => e
+      Result.new(error: Error.new(status: 0, message: e.message))
+    end
+
+    private
+
+    def perform(method, path, json, extra_headers)
+      uri = URI.parse(@base + path)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+      klass = { get: Net::HTTP::Get, post: Net::HTTP::Post, delete: Net::HTTP::Delete }.fetch(method)
+      req = klass.new(uri.request_uri)
+      req["Authorization"] = "Bearer #{@key}"
+      req["Accept"] = "application/json"
+      req["User-Agent"] = "sealpost-ruby/#{Sealpost::VERSION}"
+      extra_headers.each { |k, v| req[k] = v }
+      if json
+        req["Content-Type"] = "application/json"
+        req.body = json
+      end
+      http.request(req)
+    end
+
+    def parse(raw)
+      v = JSON.parse(raw.to_s)
+      v.is_a?(Hash) ? v : { "_" => v }
+    rescue JSON::ParserError
+      {}
+    end
+  end
+end

data/lib/sealpost/webhooks.rb

@@ -0,0 +1,35 @@
+module Sealpost
+  # Verification of Sealpost outbound webhooks. The Sealpost-Signature header is "t=<unix seconds>,v1=<hex>" where
+  # v1 = HMAC-SHA256(secret, "<t>.<raw body>"). Always verify against the raw body.
+  module Webhooks
+    SIGNATURE_HEADER = "Sealpost-Signature".freeze
+    DEFAULT_TOLERANCE = 300
+
+    # Returns [ok, reason]; reason is :malformed, :stale or :mismatch when not ok.
+    def self.verify(secret, raw_body, header, tolerance: DEFAULT_TOLERANCE, now: Time.now.to_i)
+      parts = {}
+      header.to_s.split(",").each do |piece|
+        key, _, value = piece.partition("=")
+        parts[key.strip] = value.strip unless value.empty?
+      end
+      t = Integer(parts["t"], 10) rescue nil
+      v1 = parts["v1"].to_s
+      return [false, :malformed] if t.nil? || v1 !~ /\A[0-9a-f]{64}\z/
+      return [false, :stale] if (now - t).abs > tolerance
+
+      expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{t}.#{raw_body}")
+      secure_compare(expected, v1) ? [true, nil] : [false, :mismatch]
+    end
+
+    def self.sign(secret, raw_body, timestamp = Time.now.to_i)
+      "t=#{timestamp},v1=#{OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.#{raw_body}")}"
+    end
+
+    def self.secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+      result = 0
+      a.bytes.zip(b.bytes) { |x, y| result |= x ^ y }
+      result.zero?
+    end
+  end
+end

data/lib/sealpost.rb

@@ -0,0 +1,18 @@
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
+require_relative "sealpost/webhooks"
+require_relative "sealpost/client"
+
+# Ruby client for the Sealpost API. Standard library only.
+#
+#   mail = Sealpost::Client.new(api_key: ENV["SEALPOST_KEY"], base_url: "https://mail.example.com")
+#   result = mail.emails.deliver(template: "magic_link_otp_verification", to: "user@example.org",
+#                                variables: { userName: "Ada", otpCode: "482913", signInUrl: "https://app.example.com/in" })
+#   if result.error&.code == "preflight_blocked"
+#     puts result.error.preflight["checks"]   # nothing was sent
+#   end
+module Sealpost
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,49 @@
+--- !ruby/object:Gem::Specification
+name: sealpost
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sagar Pinninti
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-10-22 00:00:00.000000000 Z
+dependencies: []
+description: Send email, schedule it, read logs and received mail, manage audiences
+  and verify webhooks against a Sealpost server. Standard library only.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/sealpost.rb
+- lib/sealpost/client.rb
+- lib/sealpost/webhooks.rb
+homepage: https://github.com/isagarpinninti/sealpost
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/isagarpinninti/sealpost/tree/main/sdks/ruby
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Zero-dependency Ruby client for the self-hosted Sealpost email API
+test_files: []