sendeez 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 85eb442ceccc29ce2672d7f9667e622770bfbbd7fdc8cfbc627fab9b94587258
+  data.tar.gz: b5a13fa32a5c612f95d3f0277d687faf432dc3886b0ddd60073dc35f6cc304b1
+SHA512:
+  metadata.gz: da4c9029648fd21898a1be35db3f44f8f71a28d62e5cc1728b09ee2b522912de0a3321dacc73e011d7d9840eba34ff75de296f4eeef9cd709d45f797443ba86b
+  data.tar.gz: 5009b9ebc827fb3770196f73062e0f3ffcb0f0a02d8c0d08f4f5b2809539a3dfed05311dc553b4604a44c3857cfe061a0e9eb5f84560a801bf2533e3f6ed9eaf

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sendeez
+
+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,63 @@
+# sendeez
+
+Zero-dependency Ruby SDK for the Sendeez transactional email API.
+
+```ruby
+require "sendeez"
+
+sendeez = Sendeez::Client.new(ENV.fetch("SENDEEZ_API_KEY"))
+
+email = sendeez.emails.send_email(
+  {
+    "from" => { "email" => "hello@example.com", "name" => "Example" },
+    "to" => [{ "email" => "developer@example.com" }],
+    "subject" => "Welcome",
+    "text" => "Your account is ready."
+  },
+  idempotency_key: "welcome-user-123" # Optional. The SDK generates one when omitted.
+)
+
+puts "#{email['id']} #{email['status']}"
+```
+
+Note the input hash needs explicit `{ }` braces at the call site: `emails`
+methods take keyword arguments too (`idempotency_key:`, `timeout:`), and
+Ruby 3+ only treats a bare trailing hash as positional when it's wrapped in
+braces — otherwise it tries (and fails) to parse it as keywords.
+
+The send method is named `send_email`, not `send` — overriding `Kernel#send`
+with a method that also declares keyword parameters hits a real Ruby VM bug
+(argument count coming out as 0), not just a style concern.
+
+## Errors and agent actions
+
+```ruby
+begin
+  sendeez.emails.send_email(message)
+rescue Sendeez::Error => e
+  puts [e.code, e.param, e.request_id, e.action, e.retry_after].inspect
+end
+```
+
+The SDK retries GET requests and mutations carrying an idempotency key after
+network errors, `429`, or `5xx`. It never automatically retries an unsafe
+mutation.
+
+Every method accepts a `timeout:` (seconds). This lets applications and AI
+agents enforce their own execution deadline:
+
+```ruby
+sendeez.emails.list(timeout: 5)
+```
+
+## Testing
+
+Pass `transport:` to substitute a fake transport, the same role `fetch`/
+`opener`/`transport` injection plays in the Node, Python, and PHP SDKs:
+
+```ruby
+fake_transport = lambda do |method, url, headers, body, timeout|
+  { status: 200, headers: {}, body: "{}" }
+end
+client = Sendeez::Client.new("sendeez_example_secret", transport: fake_transport)
+```

data/lib/sendeez/admin.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Sendeez
+  class Admin
+    def initialize(client)
+      @client = client
+    end
+
+    def diagnostics(timeout: nil)
+      @client.request("GET", "/v1/admin/diagnostics", timeout: timeout)
+    end
+  end
+end

data/lib/sendeez/api_keys.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Sendeez
+  class ApiKeys
+    def initialize(client)
+      @client = client
+    end
+
+    def create(name, scopes, expires_at: nil, timeout: nil)
+      body = { "name" => name, "scopes" => scopes }
+      body["expires_at"] = expires_at if expires_at
+      @client.request("POST", "/v1/api-keys", body: body, timeout: timeout)
+    end
+
+    def list(timeout: nil)
+      @client.request("GET", "/v1/api-keys", timeout: timeout)
+    end
+
+    def rotate(id, timeout: nil)
+      @client.request("POST", "/v1/api-keys/#{URI.encode_www_form_component(id)}/rotate", timeout: timeout)
+    end
+
+    def remove(id, timeout: nil)
+      @client.request("DELETE", "/v1/api-keys/#{URI.encode_www_form_component(id)}", timeout: timeout)
+    end
+  end
+end

data/lib/sendeez/client.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Sendeez
+  # Client for the Sendeez transactional email API.
+  #
+  # Zero runtime dependencies: HTTP is done with Net::HTTP. Pass +transport+
+  # to substitute a fake transport in tests (same role as injecting +fetch+/
+  # +opener+ in the Node and Python SDKs).
+  class Client
+    DEFAULT_BASE_URL = "https://api.sendeez.com"
+
+    attr_reader :emails, :domains, :suppressions, :webhooks, :api_keys, :admin
+
+    def initialize(api_key, base_url: DEFAULT_BASE_URL, max_retries: 2, timeout: 30, transport: nil)
+      raise ArgumentError, "Sendeez api_key is required" if api_key.nil? || api_key.empty?
+
+      @api_key = api_key
+      @base_url = base_url.chomp("/")
+      @max_retries = max_retries
+      @timeout = timeout
+      @transport = transport || method(:default_transport)
+
+      @emails = Emails.new(self)
+      @domains = Domains.new(self)
+      @suppressions = Suppressions.new(self)
+      @webhooks = Webhooks.new(self)
+      @api_keys = ApiKeys.new(self)
+      @admin = Admin.new(self)
+    end
+
+    def self.new_idempotency_key
+      "sdk_#{SecureRandom.uuid}"
+    end
+
+    # @api private used by Sendeez::{Emails,Domains,...}; not part of the public API.
+    def request(method, path, body: nil, query: nil, idempotency_key: nil, timeout: nil)
+      url = "#{@base_url}#{path}"
+      if query
+        filtered = query.reject { |_, v| v.nil? }
+        url += "?#{URI.encode_www_form(filtered)}" unless filtered.empty?
+      end
+
+      headers = {
+        "Authorization" => "Bearer #{@api_key}",
+        "Accept" => "application/json"
+      }
+      payload = nil
+      unless body.nil?
+        payload = JSON.generate(body)
+        headers["Content-Type"] = "application/json"
+      end
+      headers["Idempotency-Key"] = idempotency_key if idempotency_key
+
+      effective_timeout = timeout || @timeout
+      attempt = 0
+
+      loop do
+        begin
+          response = @transport.call(method, url, headers, payload, effective_timeout)
+        rescue StandardError => e
+          raise e if attempt >= @max_retries || (method != "GET" && idempotency_key.nil?)
+
+          sleep(backoff(attempt))
+          attempt += 1
+          next
+        end
+
+        status = response[:status]
+        if status >= 200 && status < 300
+          body_str = response[:body]
+          return nil if status == 204 || body_str.nil? || body_str.empty?
+
+          return JSON.parse(body_str)
+        end
+
+        error_payload = parse_error_body(response[:body])
+        retry_after = parse_retry_after(response[:headers])
+
+        if attempt < @max_retries && retryable?(method, idempotency_key, status)
+          sleep(retry_after || backoff(attempt))
+          attempt += 1
+          next
+        end
+
+        raise Sendeez::Error.new(status, error_payload["error"] || {}, retry_after: retry_after)
+      end
+    end
+
+    private
+
+    def retryable?(method, idempotency_key, status)
+      (method == "GET" || !idempotency_key.nil?) && (status == 429 || status >= 500)
+    end
+
+    def parse_error_body(body)
+      return {} if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      {}
+    end
+
+    def parse_retry_after(headers)
+      return nil unless headers
+
+      value = headers["retry-after"] || headers["Retry-After"]
+      return nil unless value
+
+      seconds = Float(value)
+      [seconds, 60].min
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    def backoff(attempt)
+      2**attempt
+    end
+
+    def default_transport(method, url, headers, body, timeout)
+      uri = URI(url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.read_timeout = timeout
+      http.open_timeout = timeout
+
+      request_class = {
+        "GET" => Net::HTTP::Get,
+        "POST" => Net::HTTP::Post,
+        "DELETE" => Net::HTTP::Delete
+      }.fetch(method) { raise ArgumentError, "Unsupported method #{method}" }
+
+      req = request_class.new(uri)
+      headers.each { |key, value| req[key] = value }
+      req.body = body if body
+
+      response = http.request(req)
+      {
+        status: response.code.to_i,
+        headers: response.to_hash.transform_values(&:first),
+        body: response.body || ""
+      }
+    end
+  end
+end

data/lib/sendeez/domains.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Sendeez
+  class Domains
+    def initialize(client)
+      @client = client
+    end
+
+    def create(name, timeout: nil)
+      @client.request("POST", "/v1/domains", body: { "name" => name }, timeout: timeout)
+    end
+
+    def list(timeout: nil)
+      @client.request("GET", "/v1/domains", timeout: timeout)
+    end
+
+    def retrieve(id, timeout: nil)
+      @client.request("GET", "/v1/domains/#{URI.encode_www_form_component(id)}", timeout: timeout)
+    end
+
+    def verify(id, timeout: nil)
+      @client.request("POST", "/v1/domains/#{URI.encode_www_form_component(id)}/verify", timeout: timeout)
+    end
+
+    def remove(id, timeout: nil)
+      @client.request("DELETE", "/v1/domains/#{URI.encode_www_form_component(id)}", timeout: timeout)
+    end
+  end
+end

data/lib/sendeez/emails.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Sendeez
+  class Emails
+    def initialize(client)
+      @client = client
+    end
+
+    def send_email(input, idempotency_key: nil, timeout: nil)
+      @client.request(
+        "POST",
+        "/v1/emails",
+        body: input,
+        idempotency_key: idempotency_key || Client.new_idempotency_key,
+        timeout: timeout
+      )
+    end
+
+    def retrieve(id, timeout: nil)
+      @client.request("GET", "/v1/emails/#{URI.encode_www_form_component(id)}", timeout: timeout)
+    end
+
+    def list(limit: nil, after: nil, timeout: nil)
+      @client.request("GET", "/v1/emails", query: { "limit" => limit, "after" => after }, timeout: timeout)
+    end
+
+    def simulate_event(email_id, input, idempotency_key: nil, timeout: nil)
+      @client.request(
+        "POST",
+        "/v1/emails/#{URI.encode_www_form_component(email_id)}/events",
+        body: input,
+        idempotency_key: idempotency_key || Client.new_idempotency_key,
+        timeout: timeout
+      )
+    end
+  end
+end

data/lib/sendeez/errors.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Sendeez
+  # Raised for any non-2xx response from the Sendeez API.
+  class Error < StandardError
+    attr_reader :status, :type, :code, :param, :request_id, :details, :action, :retry_after
+
+    def initialize(status, error, retry_after: nil)
+      @status = status
+      @type = error["type"] || "api_error"
+      @code = error["code"] || "unknown_error"
+      @param = error["param"]
+      @request_id = error["request_id"]
+      @details = error["details"]
+      @action = error["action"]
+      @retry_after = retry_after
+      super(error["message"] || "Sendeez request failed with HTTP #{status}")
+    end
+  end
+end

data/lib/sendeez/suppressions.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Sendeez
+  class Suppressions
+    def initialize(client)
+      @client = client
+    end
+
+    def create(recipient, reason: nil, expires_at: nil, timeout: nil)
+      body = { "recipient" => recipient }
+      body["reason"] = reason if reason
+      body["expires_at"] = expires_at if expires_at
+      @client.request("POST", "/v1/suppressions", body: body, timeout: timeout)
+    end
+
+    def list(timeout: nil)
+      @client.request("GET", "/v1/suppressions", timeout: timeout)
+    end
+
+    def remove(id, timeout: nil)
+      @client.request("DELETE", "/v1/suppressions/#{URI.encode_www_form_component(id)}", timeout: timeout)
+    end
+  end
+end

data/lib/sendeez/version.rb

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

data/lib/sendeez/webhooks.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Sendeez
+  class Webhooks
+    def initialize(client)
+      @client = client
+    end
+
+    def create(url, description: nil, events: nil, timeout: nil)
+      body = { "url" => url }
+      body["description"] = description if description
+      body["events"] = events if events
+      @client.request("POST", "/v1/webhooks", body: body, timeout: timeout)
+    end
+
+    def list(timeout: nil)
+      @client.request("GET", "/v1/webhooks", timeout: timeout)
+    end
+
+    def retrieve(id, timeout: nil)
+      @client.request("GET", "/v1/webhooks/#{URI.encode_www_form_component(id)}", timeout: timeout)
+    end
+
+    def test(id, timeout: nil)
+      @client.request("POST", "/v1/webhooks/#{URI.encode_www_form_component(id)}/test", timeout: timeout)
+    end
+
+    def deliveries(id, timeout: nil)
+      @client.request("GET", "/v1/webhooks/#{URI.encode_www_form_component(id)}/deliveries", timeout: timeout)
+    end
+
+    def remove(id, timeout: nil)
+      @client.request("DELETE", "/v1/webhooks/#{URI.encode_www_form_component(id)}", timeout: timeout)
+    end
+  end
+end

data/lib/sendeez.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require "securerandom"
+
+require_relative "sendeez/version"
+require_relative "sendeez/errors"
+require_relative "sendeez/client"
+require_relative "sendeez/emails"
+require_relative "sendeez/domains"
+require_relative "sendeez/suppressions"
+require_relative "sendeez/webhooks"
+require_relative "sendeez/api_keys"
+require_relative "sendeez/admin"

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: sendeez
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sendeez
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Sendeez::Client wraps the Sendeez transactional email API with no gem
+  runtime dependencies, using Net::HTTP directly.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/sendeez.rb
+- lib/sendeez/admin.rb
+- lib/sendeez/api_keys.rb
+- lib/sendeez/client.rb
+- lib/sendeez/domains.rb
+- lib/sendeez/emails.rb
+- lib/sendeez/errors.rb
+- lib/sendeez/suppressions.rb
+- lib/sendeez/version.rb
+- lib/sendeez/webhooks.rb
+homepage: https://github.com/sendeezhq/sendeez-ruby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/sendeezhq/sendeez-ruby
+  bug_tracker_uri: https://github.com/sendeezhq/sendeez-ruby/issues
+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: Zero-dependency Ruby SDK for the Sendeez transactional email API.
+test_files: []