groundmail 0.8.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c04be29498d0ca9868ae52b53bcc0528b588f8a2d98f4f18cf20b0f39c6a25e2
+  data.tar.gz: 5586355da81959fc4f7d9979ca51edf10cb20feea7db7809d5f612740b4138d9
+SHA512:
+  metadata.gz: a3e6a375f80c44fd28e9a2f0236c60155b31a955772db2205276ceb3512594e97e5eb7b1171c03c9c50b3dcb88b1612e9a76d19a78cd91fa1d7e64290a5547e1
+  data.tar.gz: 736c04b506e1597cef883890bcdfbde1c5e9022aeb1c46f3abb5787018d18b04c49f67f72d4c37e1d0f8f849c96458c35c6811de41e88f5e53e95c5e6264ef1f

data/.gitignore

@@ -0,0 +1,4 @@
+/spec/reports/
+/.bundle/
+/Gemfile.lock
+*.gem

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+group :development, :test do
+  gem "minitest", "~> 5.25"
+  gem "mail", ">= 2.8"
+  gem "base64", ">= 0.2"
+end

data/README.md

@@ -0,0 +1,33 @@
+# Groundmail Ruby SDK
+
+Official Ruby client for the [Groundmail](https://groundmail.dev) transactional email API.
+
+```bash
+gem install groundmail
+```
+
+```ruby
+require "groundmail"
+
+tx = Groundmail::Client.new("gm_your_key_here")
+
+result = tx.emails.send(
+  from: "you@yourdomain.com",
+  to: "user@example.com",
+  subject: "Hello",
+  html: "<p>It works.</p>"
+)
+
+puts result["id"], result["status"]
+```
+
+## Rails ActionMailer
+
+```ruby
+config.action_mailer.delivery_method = :groundmail
+config.action_mailer.groundmail_settings = {
+  api_key: ENV.fetch("GROUNDMAIL_API_KEY")
+}
+```
+
+Docs: https://docs.groundmail.dev/sdks/ruby

data/groundmail.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "lib/groundmail/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "groundmail"
+  spec.version = Groundmail::VERSION
+  spec.authors = ["Groundmail"]
+  spec.email = ["support@groundmail.dev"]
+
+  spec.summary = "Groundmail transactional email API client for Ruby"
+  spec.description = "Official Ruby client for the Groundmail REST API."
+  spec.homepage = "https://groundmail.dev"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1.0"
+
+  spec.metadata = {
+    "homepage_uri" => spec.homepage,
+    "source_code_uri" => "https://github.com/Groundmail/groundmail-sdks/tree/main/ruby",
+    "documentation_uri" => "https://docs.groundmail.dev/sdks/ruby",
+    "rubygems_mfa_required" => "true"
+  }
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject { |f| f.start_with?("spec/") }
+  rescue StandardError
+    Dir.glob("{lib}/**/*", base: __dir__) + ["README.md", "groundmail.gemspec"]
+  end
+
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "base64", ">= 0.2"
+  spec.add_development_dependency "mail", ">= 2.8"
+  spec.add_development_dependency "minitest", "~> 5.25"
+end

data/lib/groundmail/client.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Groundmail
+  class Client
+    attr_reader :emails, :domains, :webhooks, :templates, :suppressions
+
+    def initialize(api_key, base_url: HttpClient::DEFAULT_API_BASE_URL, transport: nil)
+      http = HttpClient.new(api_key, base_url: base_url, transport: transport)
+      @emails = EmailsResource.new(http)
+      @domains = DomainsResource.new(http)
+      @webhooks = WebhooksResource.new(http)
+      @templates = TemplatesResource.new(http)
+      @suppressions = SuppressionsResource.new(http)
+      @http = http
+    end
+
+    def request(method, path, body: nil, headers: {})
+      @http.request(method, path, body: body, headers: headers)
+    end
+  end
+end

data/lib/groundmail/delivery_method.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "mail"
+require_relative "message_mapper"
+
+module Groundmail
+  # ActionMailer delivery method: config.action_mailer.delivery_method = :groundmail
+  class DeliveryMethod
+    def initialize(settings = {})
+      @settings = settings || {}
+      @client = @settings[:client] || build_client
+    end
+
+    def deliver!(mail)
+      params = MessageMapper.to_send_params(mail)
+      result = @client.emails.send(**params)
+      message_id = result.is_a?(Hash) ? (result["id"] || result[:id]) : nil
+      mail.message_id = message_id if message_id && mail.respond_to?(:message_id=)
+      result
+    rescue Groundmail::Error => e
+      # Re-raise as Groundmail::Error (not a bare String → RuntimeError) so
+      # ActionMailer / rescue_from can read status, details, and error_code.
+      raise Groundmail::Error.new(
+        "Groundmail API error: #{e.message}",
+        status: e.status,
+        details: e.details,
+        error_code: e.error_code,
+        upgrade_url: e.upgrade_url
+      )
+    end
+
+    private
+
+    def build_client
+      api_key = @settings[:api_key] || @settings["api_key"] || ENV["GROUNDMAIL_API_KEY"]
+      raise ArgumentError, "GROUNDMAIL_API_KEY is not configured." if api_key.nil? || api_key.to_s.empty?
+
+      base_url = @settings[:base_url] || @settings["base_url"] || ENV["GROUNDMAIL_BASE_URL"]
+      if base_url && !base_url.to_s.empty?
+        Client.new(api_key, base_url: base_url)
+      else
+        Client.new(api_key)
+      end
+    end
+  end
+end

data/lib/groundmail/error.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Groundmail
+  class Error < StandardError
+    attr_reader :status, :details, :error_code, :upgrade_url
+
+    def initialize(message, status:, details: nil, error_code: nil, upgrade_url: nil)
+      super(message)
+      @status = status
+      @details = details
+      @error_code = error_code
+      @upgrade_url = upgrade_url
+    end
+
+    def self.from_response(status, body)
+      err = body.is_a?(Hash) ? body["error"] : nil
+
+      case err
+      when String
+        new(err, status: status)
+      when Hash
+        new(
+          err["message"] || "Request failed with status #{status}",
+          status: status,
+          details: err["details"],
+          error_code: err["code"]&.to_s,
+          upgrade_url: err["upgrade_url"]&.to_s
+        )
+      else
+        new("Request failed with status #{status}", status: status)
+      end
+    end
+  end
+end

data/lib/groundmail/http.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Groundmail
+  class HttpClient
+    DEFAULT_API_BASE_URL = "https://api.groundmail.dev"
+
+    def initialize(api_key, base_url: DEFAULT_API_BASE_URL, transport: nil)
+      raise ArgumentError, "Groundmail API key must start with gm_" unless api_key.start_with?("gm_")
+
+      @api_key = api_key
+      @base_url = base_url.chomp("/")
+      @transport = transport
+    end
+
+    def request(method, path, body: nil, headers: {})
+      request_headers = {
+        "Authorization" => "Bearer #{@api_key}",
+        "Content-Type" => "application/json"
+      }.merge(headers)
+
+      return @transport.call(method, path, body, request_headers) if @transport
+
+      uri = URI.parse("#{@base_url}#{path}")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+
+      request_class = Net::HTTP.const_get(method.capitalize)
+      request = request_class.new(uri.request_uri)
+      request_headers.each { |key, value| request[key] = value }
+      request.body = JSON.generate(body) if body
+
+      response = http.request(request)
+      parsed = response.body.to_s.empty? ? {} : JSON.parse(response.body)
+
+      raise Error.from_response(response.code.to_i, parsed) if response.code.to_i >= 400
+
+      parsed
+    end
+
+    def query(params)
+      filtered = params.compact
+      return "" if filtered.empty?
+
+      "?#{URI.encode_www_form(filtered)}"
+    end
+  end
+end

data/lib/groundmail/message_mapper.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module Groundmail
+  # Maps a Mail::Message into emails.send keyword args.
+  module MessageMapper
+    HEADER_IDEMPOTENCY = "X-Groundmail-Idempotency-Key"
+    HEADER_SCHEDULED_AT = "X-Groundmail-Scheduled-At"
+    HEADER_TAG = "X-Groundmail-Tag"
+
+    RESERVED_HEADERS = %w[
+      from to cc bcc reply-to subject content-type mime-version date message-id
+      x-groundmail-idempotency-key x-groundmail-scheduled-at x-groundmail-tag
+      idempotency-key
+    ].freeze
+
+    module_function
+
+    def to_send_params(mail)
+      from = format_addresses(mail[:from])
+      raise ArgumentError, "Email is missing a From address." if from.empty?
+
+      to = format_addresses(mail[:to])
+      raise ArgumentError, "Email is missing a To recipient." if to.empty?
+
+      html = html_body(mail)
+      text = text_body(mail)
+      raise ArgumentError, "Email must include html or text content." if html.nil? && text.nil?
+
+      params = {
+        from: from.length == 1 ? from[0] : from,
+        to: to.length == 1 ? to[0] : to
+      }
+      params[:subject] = mail.subject if mail.subject && !mail.subject.empty?
+      params[:html] = html if html
+      params[:text] = text if text
+
+      reply_to = format_addresses(mail[:reply_to])
+      params[:reply_to] = reply_to.length == 1 ? reply_to[0] : reply_to unless reply_to.empty?
+
+      cc = format_addresses(mail[:cc])
+      params[:cc] = cc unless cc.empty?
+      bcc = format_addresses(mail[:bcc])
+      params[:bcc] = bcc unless bcc.empty?
+
+      attachments = map_attachments(mail)
+      params[:attachments] = attachments unless attachments.empty?
+
+      tags = extract_tags(mail)
+      params[:tags] = tags unless tags.empty?
+
+      headers = extract_forward_headers(mail)
+      params[:headers] = headers unless headers.empty?
+
+      idem = header_value(mail, HEADER_IDEMPOTENCY) || header_value(mail, "Idempotency-Key")
+      params[:idempotency_key] = idem if idem
+
+      scheduled = header_value(mail, HEADER_SCHEDULED_AT)
+      params[:scheduled_at] = scheduled if scheduled
+
+      params
+    end
+
+    def format_addresses(field)
+      return [] if field.nil?
+
+      Array(field.addrs).filter_map do |addr|
+        email = addr.address.to_s.strip
+        next if email.empty?
+
+        name = addr.display_name.to_s.strip
+        name.empty? ? email : "#{name} <#{email}>"
+      end
+    end
+
+    def html_body(mail)
+      if mail.html_part
+        mail.html_part.decoded
+      elsif mail.mime_type == "text/html"
+        mail.decoded
+      end
+    end
+
+    def text_body(mail)
+      if mail.text_part
+        mail.text_part.decoded
+      elsif mail.mime_type == "text/plain" || (!mail.multipart? && mail.mime_type.nil?)
+        body = mail.body.decoded
+        body && !body.empty? ? body : nil
+      end
+    end
+
+    def map_attachments(mail)
+      mail.attachments.map do |attachment|
+        {
+          "filename" => attachment.filename.to_s.empty? ? "attachment" : attachment.filename,
+          "content_type" => attachment.mime_type || "application/octet-stream",
+          "content" => Base64.strict_encode64(attachment.body.decoded)
+        }
+      end
+    end
+
+    def extract_tags(mail)
+      values = mail.header[HEADER_TAG]
+      return [] unless values
+
+      list = values.respond_to?(:map) ? values.map(&:to_s) : [values.to_s]
+      list.filter_map do |raw|
+        trimmed = raw.strip
+        next if trimmed.empty?
+
+        if trimmed.include?("=")
+          name, value = trimmed.split("=", 2)
+          next if name.strip.empty? || value.strip.empty?
+
+          { "name" => name.strip, "value" => value.strip }
+        else
+          { "name" => "tag", "value" => trimmed }
+        end
+      end
+    end
+
+    def extract_forward_headers(mail)
+      out = {}
+      mail.header.fields.each do |field|
+        name = field.name.to_s
+        lower = name.downcase
+        next if RESERVED_HEADERS.include?(lower)
+        next if lower.start_with?("content-")
+
+        value = field.value.to_s.strip
+        out[name] = value unless value.empty?
+      end
+      out
+    end
+
+    def header_value(mail, name)
+      field = mail.header[name]
+      return nil unless field
+
+      value = field.respond_to?(:last) ? field.last.to_s : field.to_s
+      value = value.strip
+      value.empty? ? nil : value
+    end
+  end
+end

data/lib/groundmail/railtie.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+require_relative "delivery_method"
+
+module Groundmail
+  class Railtie < ::Rails::Railtie
+    initializer "groundmail.add_delivery_method" do
+      ActiveSupport.on_load(:action_mailer) do
+        ActionMailer::Base.add_delivery_method :groundmail, Groundmail::DeliveryMethod
+      end
+    end
+  end
+end

data/lib/groundmail/resources.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module Groundmail
+  class EmailsResource
+    def initialize(http)
+      @http = http
+    end
+
+    def list(limit: nil, cursor: nil)
+      @http.request("GET", "/emails#{@http.query({ "limit" => limit, "cursor" => cursor })}")
+    end
+
+    def get(email_id)
+      @http.request("GET", "/emails/#{URI.encode_www_form_component(email_id)}")
+    end
+
+    def send(from: nil, to: nil, **params)
+      params["from"] = from if from
+      params["to"] = to if to
+      body = serialize_send_params(params)
+      headers = {}
+      idempotency_key =
+        params["idempotency_key"] || params[:idempotency_key] ||
+        params["idempotencyKey"] || params[:idempotencyKey]
+      headers["Idempotency-Key"] = idempotency_key.to_s if idempotency_key
+
+      @http.request("POST", "/emails", body: body, headers: headers)
+    end
+
+    def batch(emails)
+      serialized = emails.map { |email| serialize_send_params(email) }
+      @http.request("POST", "/emails/batch", body: { "emails" => serialized })
+    end
+
+    def cancel(email_id)
+      @http.request("PATCH", "/emails/#{URI.encode_www_form_component(email_id)}", body: { "cancel" => true })
+    end
+
+    def resend(email_id)
+      @http.request("POST", "/emails/#{URI.encode_www_form_component(email_id)}/resend")
+    end
+
+    def test_webhook(**params)
+      @http.request("POST", "/emails/test", body: params)
+    end
+
+    def insights(window: "30d")
+      @http.request("GET", "/deliverability#{@http.query({ "window" => window })}")
+    end
+
+    private
+
+    def serialize_send_params(params)
+      body = {
+        "from" => params["from"] || params[:from],
+        "to" => params["to"] || params[:to]
+      }
+
+      %w[subject html text reply_to replyTo cc bcc tags headers tag template attachments].each do |key|
+        value = params[key] || params[key.to_sym]
+        next if value.nil?
+
+        mapped = key == "replyTo" ? "reply_to" : key
+        body[mapped] = value
+      end
+
+      body["html"] = params["htmlBody"] || params[:htmlBody] if params["htmlBody"] || params[:htmlBody]
+      body["text"] = params["textBody"] || params[:textBody] if params["textBody"] || params[:textBody]
+      body["scheduled_at"] = params["scheduled_at"] || params[:scheduled_at] if params["scheduled_at"] || params[:scheduled_at]
+      body["scheduled_at"] ||= params["scheduledAt"] || params[:scheduledAt]
+      body["unsubscribe"] = params["unsubscribe"] || params[:unsubscribe] if params.key?("unsubscribe") || params.key?(:unsubscribe)
+
+      body
+    end
+  end
+
+  class DomainsResource
+    def initialize(http)
+      @http = http
+    end
+
+    def list(limit: nil, cursor: nil, inbound_enabled: nil)
+      @http.request(
+        "GET",
+        "/domains#{@http.query({ "limit" => limit, "cursor" => cursor, "inbound_enabled" => inbound_enabled })}"
+      )
+    end
+
+    def get(id_or_name)
+      @http.request("GET", "/domains/#{URI.encode_www_form_component(id_or_name)}")
+    end
+
+    def create(name, inbound_enabled: nil)
+      body = { "name" => name }
+      body["inbound_enabled"] = inbound_enabled unless inbound_enabled.nil?
+      @http.request("POST", "/domains", body: body)
+    end
+
+    def verify(id_or_name)
+      @http.request("POST", "/domains/#{URI.encode_www_form_component(id_or_name)}", body: { "action" => "verify" })
+    end
+
+    def apply(id_or_name, provider: "cloudflare", credentials: nil)
+      body = { "action" => "apply", "provider" => provider }
+      body["credentials"] = credentials if credentials
+      @http.request("POST", "/domains/#{URI.encode_www_form_component(id_or_name)}", body: body)
+    end
+
+    def update(id_or_name, **params)
+      @http.request("PATCH", "/domains/#{URI.encode_www_form_component(id_or_name)}", body: params)
+    end
+
+    def delete(id_or_name)
+      @http.request("DELETE", "/domains/#{URI.encode_www_form_component(id_or_name)}")
+    end
+  end
+
+  class WebhooksResource
+    def initialize(http)
+      @http = http
+    end
+
+    def list(limit: nil, cursor: nil)
+      @http.request("GET", "/webhooks#{@http.query({ "limit" => limit, "cursor" => cursor })}")
+    end
+
+    def get(webhook_id)
+      @http.request("GET", "/webhooks/#{URI.encode_www_form_component(webhook_id)}")
+    end
+
+    def create(**params)
+      @http.request("POST", "/webhooks", body: params)
+    end
+
+    def update(webhook_id, **params)
+      @http.request("PATCH", "/webhooks/#{URI.encode_www_form_component(webhook_id)}", body: params)
+    end
+
+    def delete(webhook_id)
+      @http.request("DELETE", "/webhooks/#{URI.encode_www_form_component(webhook_id)}")
+    end
+  end
+
+  class TemplatesResource
+    def initialize(http)
+      @http = http
+    end
+
+    def list(limit: nil, cursor: nil, status: nil)
+      @http.request(
+        "GET",
+        "/templates#{@http.query({ "limit" => limit, "cursor" => cursor, "status" => status })}"
+      )
+    end
+
+    def get(id_or_alias)
+      @http.request("GET", "/templates/#{URI.encode_www_form_component(id_or_alias)}")
+    end
+
+    def create(**params)
+      @http.request("POST", "/templates", body: params)
+    end
+
+    def update(id_or_alias, **params)
+      @http.request("PATCH", "/templates/#{URI.encode_www_form_component(id_or_alias)}", body: params)
+    end
+
+    def delete(id_or_alias)
+      @http.request("DELETE", "/templates/#{URI.encode_www_form_component(id_or_alias)}")
+    end
+
+    def publish(id_or_alias)
+      @http.request("POST", "/templates/#{URI.encode_www_form_component(id_or_alias)}", body: { "action" => "publish" })
+    end
+  end
+
+  class SuppressionsResource
+    def initialize(http)
+      @http = http
+    end
+
+    def list(limit: nil, cursor: nil, email: nil)
+      @http.request(
+        "GET",
+        "/suppressions#{@http.query({ "limit" => limit, "cursor" => cursor, "email" => email })}"
+      )
+    end
+
+    def create(**params)
+      @http.request("POST", "/suppressions", body: params)
+    end
+
+    def remove(id_or_email)
+      if id_or_email.include?("@")
+        return @http.request("DELETE", "/suppressions#{@http.query({ "email" => id_or_email })}")
+      end
+
+      @http.request("DELETE", "/suppressions/#{URI.encode_www_form_component(id_or_email)}")
+    end
+  end
+end

data/lib/groundmail/version.rb

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

data/lib/groundmail.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "groundmail/version"
+require_relative "groundmail/error"
+require_relative "groundmail/http"
+require_relative "groundmail/resources"
+require_relative "groundmail/client"
+
+module Groundmail
+end
+
+begin
+  require "base64"
+  require "mail"
+rescue LoadError
+  # base64/mail are optional; required for ActionMailer delivery method.
+else
+  require_relative "groundmail/message_mapper"
+  require_relative "groundmail/delivery_method"
+end
+
+begin
+  require "rails"
+rescue LoadError
+  # Rails is optional.
+else
+  require_relative "groundmail/railtie"
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: groundmail
+version: !ruby/object:Gem::Version
+  version: 0.8.3
+platform: ruby
+authors:
+- Groundmail
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: mail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.8'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+description: Official Ruby client for the Groundmail REST API.
+email:
+- support@groundmail.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- README.md
+- groundmail.gemspec
+- lib/groundmail.rb
+- lib/groundmail/client.rb
+- lib/groundmail/delivery_method.rb
+- lib/groundmail/error.rb
+- lib/groundmail/http.rb
+- lib/groundmail/message_mapper.rb
+- lib/groundmail/railtie.rb
+- lib/groundmail/resources.rb
+- lib/groundmail/version.rb
+homepage: https://groundmail.dev
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://groundmail.dev
+  source_code_uri: https://github.com/Groundmail/groundmail-sdks/tree/main/ruby
+  documentation_uri: https://docs.groundmail.dev/sdks/ruby
+  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.1.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: Groundmail transactional email API client for Ruby
+test_files: []