camelmailer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f9d144156fc057f5dede175ed29f43b9c6587a33ae84b7b25c097a814c1537b7
+  data.tar.gz: 482b37a49af5b42f3a527788a59c1dfaeb115797ed985c202deb7841c8fd8058
+SHA512:
+  metadata.gz: 865924a5a43a2087e6e73abfb70e5fbb677b7cf9d961aa893bca18eec7859320f7a879d97a4d22d16e37d1b1840f1490ea1436692a357aa74aa24302a4d29801
+  data.tar.gz: a14c759e870581dec25f9a8eb3bd1cdf2e24ba4e9a9989d9128193e45858ee1f51022dc5a7886e33f31f7d2c61d6c5b60766f42fd95a498c85e892282cfb15b3

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-11
+
+### Added
+
+- `CamelMailer::Client` on stdlib net/http — zero runtime dependencies.
+- Global configuration via `CamelMailer.configure` (api_key, base_url for self-hosted instances).
+- Messaging resources: `Emails` (send, send_batch, send_with_template, send_with_template_batch, get, list, deliveries, opens, clicks, raw), `Templates` (list, create, get, update, archive, render), `Streams` (list, create, get, update, archive), `Stats` (get, deliveries), `Bounces` (list, get), `Dmarc` (summary, reports, report).
+- Typed error hierarchy with `code`, `message` and `status_code` (`UnauthorizedError`, `ForbiddenError`, `NotFoundError`, `ValidationError`, `ParameterMissingError`, `ServerError`, `ConnectionError`).
+- Rails integration: `:camelmailer` ActionMailer delivery method with full MIME mapping (from/to/cc/bcc/reply_to, html+text parts, attachments, custom headers, tag/stream/metadata pseudo-headers).
+- RBS type signatures.
+
+[Unreleased]: https://github.com/camelmailer/camelmailer-ruby/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/camelmailer/camelmailer-ruby/releases/tag/v0.1.0

data/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing
+
+## Setup
+
+```sh
+git clone https://github.com/camelmailer/camelmailer-ruby
+cd camelmailer-ruby
+bundle install
+```
+
+Requires Ruby >= 3.1.
+
+## Tests & lint
+
+```sh
+bundle exec rspec      # unit tests (WebMock, no network)
+bundle exec rubocop    # lint
+bundle exec rake       # both
+```
+
+Integration tests run against a real instance and are skipped without credentials:
+
+```sh
+CAMELMAILER_API_KEY=cm_... CAMELMAILER_BASE_URL=https://mail.example.com \
+CAMELMAILER_FROM=billing@acme.com CAMELMAILER_TO=inbox@example.com \
+bundle exec rspec spec/integration
+```
+
+## Conventions
+
+- Test-first: every resource method and error path has a spec against a mocked HTTP layer.
+- No runtime dependencies — stdlib `net/http` only.
+- Follow the existing envelope handling in `CamelMailer::Client`; new endpoints go on the matching resource class plus an `expose` entry for the class-level API.
+- Update `CHANGELOG.md` (Keep a Changelog) with user-visible changes.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Camelmailer contributors
+
+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,167 @@
+# camelmailer-ruby
+
+[![CI](https://github.com/camelmailer/camelmailer-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/camelmailer/camelmailer-ruby/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/camelmailer)](https://rubygems.org/gems/camelmailer)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+The Ruby and Rails SDK for [Camelmailer](https://camelmailer.com) — open-source transactional email. No runtime dependencies, Ruby >= 3.1.
+
+## Install
+
+```sh
+gem install camelmailer
+# or in your Gemfile
+gem "camelmailer"
+```
+
+## Quickstart
+
+```ruby
+require "camelmailer"
+
+CamelMailer.configure { |c| c.api_key = "cm_..." }
+
+CamelMailer::Emails.send(
+  from: "billing@acme.com",
+  to: ["ada@example.com"],
+  subject: "Your receipt",
+  html_body: "<h1>Thanks!</h1>"
+)
+```
+
+Or without global state:
+
+```ruby
+client = CamelMailer::Client.new(api_key: "cm_...")
+client.emails.send(from: "billing@acme.com", to: ["ada@example.com"], subject: "Hi", text_body: "Hello")
+```
+
+Every resource is available both ways: `CamelMailer::Emails.send(...)` uses the global configuration, `client.emails.send(...)` uses an explicit client.
+
+## Self-hosted
+
+The base URL defaults to the Camelmailer cloud (`https://app.camelmailer.com`). Point it at your own instance:
+
+```ruby
+CamelMailer.configure do |c|
+  c.api_key = "cm_..."
+  c.base_url = "https://mail.example.com"
+end
+```
+
+## Rails
+
+The gem registers the `:camelmailer` ActionMailer delivery method automatically:
+
+```ruby
+# config/environments/production.rb
+config.action_mailer.delivery_method = :camelmailer
+config.action_mailer.camelmailer_settings = {
+  api_key: Rails.application.credentials.dig(:camelmailer, :api_key),
+  base_url: "https://mail.example.com" # optional, self-hosted only
+}
+```
+
+Then use ActionMailer as usual — including attachments, multipart bodies and custom headers:
+
+```ruby
+class ReceiptMailer < ApplicationMailer
+  def receipt
+    attachments["invoice.pdf"] = File.read("invoice.pdf")
+    mail(
+      from: "billing@acme.com",
+      to: params[:to],
+      subject: "Your receipt",
+      tag: "receipt",              # CamelMailer tag (filtering & stats)
+      stream: "transactional"      # optional message stream
+    )
+  end
+end
+```
+
+## Resources
+
+### Emails
+
+```ruby
+CamelMailer::Emails.send(from:, to:, subject:, html_body:, text_body:, cc:, bcc:, reply_to:, headers:, attachments:, tag:, metadata:, stream:)
+CamelMailer::Emails.send_batch([{ from:, to:, ... }, ...])
+CamelMailer::Emails.send_with_template(from:, to:, template: "welcome", template_model: { name: "Ada" })
+CamelMailer::Emails.send_with_template_batch([...])
+CamelMailer::Emails.get(42)
+CamelMailer::Emails.list(scope: "outgoing", status: "Sent", tag: "receipt", query: "ada", page: 1, per_page: 50)
+CamelMailer::Emails.deliveries(42)  # delivery attempts
+CamelMailer::Emails.opens(42)       # open events
+CamelMailer::Emails.clicks(42)      # click events
+CamelMailer::Emails.raw(42)         # raw RFC 5322 source
+```
+
+Attachments are `{ name:, content_type:, data_base64: }`; addresses are either `"a@b.com"` or `{ email: "a@b.com", name: "Ada" }`.
+
+### Templates
+
+```ruby
+CamelMailer::Templates.list
+CamelMailer::Templates.create(name: "Welcome", subject: "Hi {{ name }}", html_body: "<p>Hi {{ name }}</p>")
+CamelMailer::Templates.get("welcome")
+CamelMailer::Templates.update("welcome", subject: "Hello {{ name }}")
+CamelMailer::Templates.archive("welcome")
+CamelMailer::Templates.render("welcome", { name: "Ada" }) # preview without sending
+```
+
+### Streams
+
+```ruby
+CamelMailer::Streams.list
+CamelMailer::Streams.create(name: "Broadcasts", stream_type: "broadcast")
+CamelMailer::Streams.get("broadcasts")
+CamelMailer::Streams.update("broadcasts", name: "News")
+CamelMailer::Streams.archive("broadcasts")
+```
+
+### Stats & bounces
+
+```ruby
+CamelMailer::Stats.get(from: "2026-01-01T00:00:00Z", to: "2026-02-01T00:00:00Z")
+CamelMailer::Stats.deliveries
+CamelMailer::Bounces.list(page: 1, per_page: 50)
+CamelMailer::Bounces.get(42)
+```
+
+### DMARC
+
+```ruby
+CamelMailer::Dmarc.summary(domain: "acme.com")
+CamelMailer::Dmarc.reports(domain: "acme.com", page: 1)
+CamelMailer::Dmarc.report(3)
+```
+
+## Error handling
+
+All API errors raise typed exceptions with `code`, `message` and `status_code`:
+
+```ruby
+begin
+  CamelMailer::Emails.send(from: "x@unverified.test", to: ["a@b.com"])
+rescue CamelMailer::ValidationError => e
+  e.code        # => "ValidationError"
+  e.message     # => "from domain not verified"
+  e.status_code # => 422
+rescue CamelMailer::UnauthorizedError
+  # bad API key
+rescue CamelMailer::ConnectionError
+  # network problem
+rescue CamelMailer::Error => e
+  # everything above inherits from this
+end
+```
+
+Hierarchy: `Error` → `ConnectionError`, `APIError` → `UnauthorizedError`, `ForbiddenError`, `NotFoundError`, `ValidationError`, `ParameterMissingError`, `ServerError`.
+
+## Docs
+
+Full API reference: [camelmailer.com/docs](https://camelmailer.com/docs)
+
+## License
+
+[MIT](LICENSE)

data/lib/camelmailer/bounces.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module CamelMailer
+  # Read bounce messages (/api/v2/server/bounces...).
+  class Bounces < Resource
+    expose :list, :get
+
+    # Lists bounces. Filters: page:, per_page: (max 100).
+    def list(**filters)
+      client.get("bounces", filters)
+    end
+
+    def get(id)
+      client.get("bounces/#{id}")
+    end
+  end
+end

data/lib/camelmailer/client.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
+
+module CamelMailer
+  # HTTP client for the CamelMailer messaging API (/api/v2/server).
+  #
+  #   client = CamelMailer::Client.new(api_key: "cm_...")
+  #   client.emails.send(from: "a@acme.com", to: ["b@example.com"], subject: "Hi", text_body: "Hello")
+  #
+  # Built on net/http — the gem has no runtime dependencies.
+  class Client
+    API_PREFIX = "/api/v2/server"
+
+    NETWORK_ERRORS = [
+      SocketError, EOFError, Errno::ECONNREFUSED, Errno::ECONNRESET,
+      Errno::EHOSTUNREACH, Errno::ETIMEDOUT, Errno::EPIPE,
+      Net::OpenTimeout, Net::ReadTimeout, OpenSSL::SSL::SSLError
+    ].freeze
+
+    attr_reader :api_key, :base_url, :open_timeout, :read_timeout
+
+    def initialize(api_key:, base_url: nil, open_timeout: 10, read_timeout: 30)
+      if api_key.nil? || api_key.to_s.strip.empty?
+        raise Error, "No CamelMailer API key provided — set CamelMailer.api_key or pass api_key:"
+      end
+
+      @api_key = api_key
+      @base_url = (base_url || DEFAULT_BASE_URL).to_s.chomp("/")
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+    end
+
+    def emails
+      @emails ||= Emails.new(self)
+    end
+
+    def templates
+      @templates ||= Templates.new(self)
+    end
+
+    def streams
+      @streams ||= Streams.new(self)
+    end
+
+    def stats
+      @stats ||= Stats.new(self)
+    end
+
+    def bounces
+      @bounces ||= Bounces.new(self)
+    end
+
+    def dmarc
+      @dmarc ||= Dmarc.new(self)
+    end
+
+    def get(path, query = nil)
+      perform(Net::HTTP::Get.new(build_uri(path, query)))
+    end
+
+    def post(path, body = nil)
+      req = Net::HTTP::Post.new(build_uri(path))
+      attach_body(req, body)
+      perform(req)
+    end
+
+    def patch(path, body = nil)
+      req = Net::HTTP::Patch.new(build_uri(path))
+      attach_body(req, body)
+      perform(req)
+    end
+
+    private
+
+    def build_uri(path, query = nil)
+      uri = URI.parse("#{base_url}#{API_PREFIX}/#{path}")
+      if query
+        params = query.compact
+        uri.query = URI.encode_www_form(params) unless params.empty?
+      end
+      uri
+    end
+
+    def attach_body(req, body)
+      return unless body
+
+      req["Content-Type"] = "application/json"
+      req.body = JSON.generate(body)
+    end
+
+    def perform(req)
+      req["X-Server-API-Key"] = api_key
+      req["Accept"] = "application/json"
+      req["User-Agent"] = "camelmailer-ruby/#{VERSION}"
+
+      handle(transport(req.uri).request(req))
+    rescue *NETWORK_ERRORS => e
+      raise ConnectionError, "Could not reach the CamelMailer API: #{e.class}: #{e.message}"
+    end
+
+    def transport(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = open_timeout
+      http.read_timeout = read_timeout
+      http
+    end
+
+    def handle(res)
+      status = res.code.to_i
+      body = parse_body(res.body)
+
+      case body
+      in { status: "success" }
+        body[:data] || {}
+      in { status: "error" }
+        error = body[:error] || {}
+        raise APIError.for(code: error[:code], message: error[:message], status_code: status)
+      else
+        return body.is_a?(Hash) ? body : {} if (200..299).cover?(status)
+
+        raise ServerError.new("Unexpected HTTP #{status} response from the CamelMailer API", status_code: status)
+      end
+    end
+
+    def parse_body(raw)
+      return nil if raw.nil? || raw.empty?
+
+      JSON.parse(raw, symbolize_names: true)
+    rescue JSON::ParserError
+      nil
+    end
+  end
+end

data/lib/camelmailer/dmarc.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module CamelMailer
+  # DMARC compliance summary and aggregate reports (/api/v2/server/dmarc...).
+  class Dmarc < Resource
+    expose :summary, :reports, :report
+
+    # Compliance summary. Filters: domain:, from:, to: (ISO 8601).
+    def summary(domain: nil, from: nil, to: nil)
+      client.get("dmarc/summary", { domain: domain, from: from, to: to })
+    end
+
+    # Stored aggregate reports, newest report range first.
+    def reports(domain: nil, from: nil, to: nil, page: nil, per_page: nil)
+      client.get("dmarc/reports", { domain: domain, from: from, to: to, page: page, per_page: per_page })
+    end
+
+    # One report with its records.
+    def report(id)
+      client.get("dmarc/reports/#{id}")
+    end
+  end
+end

data/lib/camelmailer/emails.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module CamelMailer
+  # Send and read messages (POST/GET /api/v2/server/messages...).
+  class Emails < Resource
+    expose :send, :send_batch, :send_with_template, :send_with_template_batch,
+           :get, :list, :deliveries, :opens, :clicks, :raw
+
+    # Sends one message. Required: from:, to:. See the API docs for the
+    # full SendRequest shape (html_body, text_body, cc, bcc, reply_to,
+    # headers, attachments, tag, metadata, stream).
+    def send(params)
+      client.post("messages", params)
+    end
+
+    # Sends a batch of SendRequest hashes; returns one result per entry.
+    def send_batch(messages)
+      client.post("messages/batch", { messages: messages })
+    end
+
+    # Renders a stored template against template_model:, then sends.
+    def send_with_template(params)
+      client.post("messages/with_template", params)
+    end
+
+    # Batch variant of #send_with_template.
+    def send_with_template_batch(messages)
+      client.post("messages/with_template/batch", { messages: messages })
+    end
+
+    # Shows one message by id.
+    def get(id)
+      client.get("messages/#{id}")
+    end
+
+    # Lists messages. Filters: scope:, status:, tag:, query:, stream:,
+    # page:, per_page: (max 100).
+    def list(**filters)
+      client.get("messages", filters)
+    end
+
+    # Delivery attempts of a message.
+    def deliveries(id)
+      client.get("messages/#{id}/deliveries")
+    end
+
+    # Open events of a message.
+    def opens(id)
+      client.get("messages/#{id}/opens")
+    end
+
+    # Click events of a message.
+    def clicks(id)
+      client.get("messages/#{id}/clicks")
+    end
+
+    # Raw RFC 5322 source of a message.
+    def raw(id)
+      client.get("messages/#{id}/raw")
+    end
+  end
+end

data/lib/camelmailer/errors.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module CamelMailer
+  # Base error for everything raised by this gem.
+  #
+  # Exposes the stable API error +code+ (e.g. "ValidationError") and the
+  # HTTP +status_code+ of the response, when available.
+  class Error < StandardError
+    attr_reader :code, :status_code
+
+    def initialize(message = nil, code: nil, status_code: nil)
+      super(message)
+      @code = code
+      @status_code = status_code
+    end
+  end
+
+  # Raised when the API could not be reached at all (DNS, TCP, TLS, timeouts).
+  class ConnectionError < Error; end
+
+  # Raised for any error envelope returned by the API. Specific stable
+  # error codes map to subclasses; unknown codes raise APIError itself.
+  class APIError < Error
+    # Builds the most specific error class for an error envelope.
+    def self.for(code:, message:, status_code: nil)
+      klass = ERROR_CODE_CLASSES.fetch(code, APIError)
+      klass.new(message || code || "CamelMailer API error", code: code, status_code: status_code)
+    end
+  end
+
+  # 401 — missing or invalid API key.
+  class UnauthorizedError < APIError; end
+
+  # 403 — the key is valid but not allowed to do this.
+  class ForbiddenError < APIError; end
+
+  # 404 — no such resource.
+  class NotFoundError < APIError; end
+
+  # 422 — the request was understood but invalid.
+  class ValidationError < APIError; end
+
+  # 400 — a required parameter is missing.
+  class ParameterMissingError < APIError; end
+
+  # Unexpected non-envelope response (e.g. a 5xx from a proxy).
+  class ServerError < APIError; end
+
+  APIError::ERROR_CODE_CLASSES = {
+    "Unauthorized" => UnauthorizedError,
+    "Forbidden" => ForbiddenError,
+    "NotFound" => NotFoundError,
+    "ValidationError" => ValidationError,
+    "ParameterMissing" => ParameterMissingError
+  }.freeze
+end

data/lib/camelmailer/mailer.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "camelmailer"
+
+module CamelMailer
+  # ActionMailer delivery method (:camelmailer).
+  #
+  #   config.action_mailer.delivery_method = :camelmailer
+  #   config.action_mailer.camelmailer_settings = {
+  #     api_key: Rails.application.credentials.dig(:camelmailer, :api_key),
+  #     base_url: "https://mail.example.com" # optional, for self-hosted
+  #   }
+  #
+  # Falls back to the global CamelMailer.configure settings when the
+  # delivery-method settings do not provide api_key/base_url.
+  #
+  # Special mail headers `tag`, `stream` and `metadata` are lifted out of
+  # the MIME headers and sent as first-class API fields:
+  #
+  #   mail(to: ..., subject: ..., tag: "receipt", stream: "transactional")
+  class Mailer
+    # MIME headers that are structural or sent as dedicated API fields —
+    # everything else is forwarded via the +headers+ API parameter.
+    IGNORED_HEADERS = %w[
+      from to cc bcc reply-to subject date message-id mime-version
+      content-type content-transfer-encoding return-path received
+      tag stream metadata headers
+    ].freeze
+
+    attr_accessor :settings
+
+    def initialize(settings = {})
+      @settings = settings || {}
+    end
+
+    # Delivers a Mail::Message through the CamelMailer API and assigns
+    # the resulting message id back onto the mail object.
+    def deliver!(mail)
+      data = Emails.new(client).send(build_params(mail))
+      mail.message_id = data[:message_id].to_s if data.is_a?(Hash) && data[:message_id]
+      data
+    end
+
+    # Maps a Mail::Message onto a CamelMailer SendRequest hash.
+    def build_params(mail)
+      params = {
+        from: single_address(mail[:from]),
+        to: address_list(mail[:to]),
+        cc: address_list(mail[:cc]),
+        bcc: address_list(mail[:bcc]),
+        reply_to: address_list(mail[:reply_to]),
+        subject: mail.subject
+      }
+      params.merge!(contents(mail))
+      params.merge!(pseudo_headers(mail))
+      headers = custom_headers(mail)
+      params[:headers] = headers unless headers.empty?
+      attachments = build_attachments(mail)
+      params[:attachments] = attachments unless attachments.empty?
+      params.compact
+    end
+
+    private
+
+    def client
+      Client.new(
+        api_key: settings[:api_key] || CamelMailer.api_key,
+        base_url: settings[:base_url] || CamelMailer.base_url
+      )
+    end
+
+    def single_address(field)
+      address_list(field)&.first
+    end
+
+    def address_list(field)
+      return nil unless field
+
+      field.addrs.map do |addr|
+        if addr.display_name
+          { email: addr.address, name: addr.display_name }
+        else
+          addr.address
+        end
+      end
+    end
+
+    def contents(mail)
+      case mail.mime_type
+      when "text/html"
+        { html_body: mail.body.decoded }
+      when "multipart/alternative", "multipart/mixed", "multipart/related"
+        multipart_contents(mail)
+      else
+        { text_body: mail.body.decoded }
+      end
+    end
+
+    def multipart_contents(mail)
+      params = {}
+      params[:text_body] = mail.text_part.decoded if mail.text_part
+      params[:html_body] = mail.html_part.decoded if mail.html_part
+      params
+    end
+
+    # Lifts the tag/stream/metadata pseudo-headers into API fields.
+    def pseudo_headers(mail)
+      params = {}
+      params[:tag] = mail["tag"].unparsed_value if mail["tag"]
+      params[:stream] = mail["stream"].unparsed_value if mail["stream"]
+      params[:metadata] = mail["metadata"].unparsed_value if mail["metadata"]
+      params
+    end
+
+    def custom_headers(mail)
+      mail.header_fields.each_with_object({}) do |field, headers|
+        next if IGNORED_HEADERS.include?(field.name.downcase)
+
+        value = field.unparsed_value
+        headers[field.name] = value.to_s unless value.nil?
+      end
+    end
+
+    def build_attachments(mail)
+      mail.attachments.map do |part|
+        {
+          name: part.filename,
+          content_type: part.mime_type,
+          data_base64: [part.body.decoded].pack("m0")
+        }
+      end
+    end
+  end
+end

data/lib/camelmailer/railtie.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "camelmailer"
+require "camelmailer/mailer"
+
+module CamelMailer
+  # Registers the :camelmailer ActionMailer delivery method in Rails apps.
+  class Railtie < ::Rails::Railtie
+    ActiveSupport.on_load(:action_mailer) do
+      add_delivery_method :camelmailer, CamelMailer::Mailer
+      ActiveSupport.run_load_hooks(:camelmailer_mailer, CamelMailer::Mailer)
+    end
+  end
+end

data/lib/camelmailer/resource.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module CamelMailer
+  # Base class for API resources.
+  #
+  # Resources are used through a client instance (client.emails.send ...)
+  # or through class-level convenience methods (CamelMailer::Emails.send ...)
+  # that use the globally configured client.
+  class Resource
+    # Defines class-level methods that delegate to an instance built
+    # from the global configuration (CamelMailer.configure).
+    def self.expose(*names)
+      names.each do |name|
+        define_singleton_method(name) do |*args, **kwargs|
+          new.public_send(name, *args, **kwargs)
+        end
+      end
+    end
+
+    attr_reader :client
+
+    def initialize(client = CamelMailer.client)
+      @client = client
+    end
+  end
+end

data/lib/camelmailer/stats.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module CamelMailer
+  # Message counters and delivery statistics (/api/v2/server/stats...).
+  class Stats < Resource
+    expose :get, :deliveries
+
+    # Message counters, optionally windowed with from:/to: (ISO 8601).
+    def get(from: nil, to: nil)
+      client.get("stats", { from: from, to: to })
+    end
+
+    # Delivery/queue statistics.
+    def deliveries
+      client.get("stats/deliveries")
+    end
+  end
+end

data/lib/camelmailer/streams.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module CamelMailer
+  # Manage message streams (/api/v2/server/streams...).
+  class Streams < Resource
+    expose :list, :create, :get, :update, :archive
+
+    def list
+      client.get("streams")
+    end
+
+    # Creates a stream. Required: name:. Optional: stream_type:
+    # ("transactional" or "broadcast").
+    def create(params)
+      client.post("streams", params)
+    end
+
+    def get(permalink)
+      client.get("streams/#{permalink}")
+    end
+
+    def update(permalink, params)
+      client.patch("streams/#{permalink}", params)
+    end
+
+    def archive(permalink)
+      client.post("streams/#{permalink}/archive")
+    end
+  end
+end

data/lib/camelmailer/templates.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module CamelMailer
+  # Manage stored message templates (/api/v2/server/templates...).
+  class Templates < Resource
+    expose :list, :create, :get, :update, :archive, :render
+
+    def list
+      client.get("templates")
+    end
+
+    # Creates a template. Required: name:. Optional: subject:, html_body:,
+    # text_body: — all may contain {{ variables }}.
+    def create(params)
+      client.post("templates", params)
+    end
+
+    def get(permalink)
+      client.get("templates/#{permalink}")
+    end
+
+    def update(permalink, params)
+      client.patch("templates/#{permalink}", params)
+    end
+
+    def archive(permalink)
+      client.post("templates/#{permalink}/archive")
+    end
+
+    # Renders the template against a model without sending anything.
+    def render(permalink, template_model = {})
+      client.post("templates/#{permalink}/render", { template_model: template_model })
+    end
+  end
+end

data/lib/camelmailer/version.rb

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

data/lib/camelmailer.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "camelmailer/version"
+require "camelmailer/errors"
+require "camelmailer/client"
+require "camelmailer/resource"
+require "camelmailer/emails"
+require "camelmailer/templates"
+require "camelmailer/streams"
+require "camelmailer/stats"
+require "camelmailer/bounces"
+require "camelmailer/dmarc"
+
+# The Ruby SDK for CamelMailer — https://camelmailer.com
+#
+#   CamelMailer.configure do |config|
+#     config.api_key = "cm_..."
+#     config.base_url = "https://mail.example.com" # optional, for self-hosted
+#   end
+#
+#   CamelMailer::Emails.send(from: "a@acme.com", to: ["b@example.com"],
+#                            subject: "Hello", text_body: "Hi!")
+#
+# Or with an explicit client (no global state):
+#
+#   client = CamelMailer::Client.new(api_key: "cm_...")
+#   client.emails.send(...)
+module CamelMailer
+  DEFAULT_BASE_URL = "https://app.camelmailer.com"
+
+  class << self
+    attr_accessor :api_key
+    attr_writer :base_url
+
+    def base_url
+      @base_url || DEFAULT_BASE_URL
+    end
+
+    def configure
+      yield self if block_given?
+      self
+    end
+    alias config configure
+
+    # A client built from the global configuration.
+    def client
+      Client.new(api_key: api_key, base_url: base_url)
+    end
+
+    # Clears the global configuration (used in tests).
+    def reset!
+      @api_key = nil
+      @base_url = nil
+    end
+  end
+end
+
+require "camelmailer/railtie" if defined?(Rails::Railtie)

data/sig/camelmailer.rbs

@@ -0,0 +1,170 @@
+module CamelMailer
+  VERSION: String
+  DEFAULT_BASE_URL: String
+
+  type payload = Hash[Symbol | String, untyped]
+  type response = Hash[Symbol, untyped]
+
+  def self.api_key: () -> String?
+  def self.api_key=: (String?) -> String?
+  def self.base_url: () -> String
+  def self.base_url=: (String?) -> String?
+  def self.configure: () { (module) -> void } -> module
+  def self.config: () { (module) -> void } -> module
+  def self.client: () -> Client
+  def self.reset!: () -> void
+
+  class Error < StandardError
+    attr_reader code: String?
+    attr_reader status_code: Integer?
+
+    def initialize: (?String? message, ?code: String?, ?status_code: Integer?) -> void
+  end
+
+  class ConnectionError < Error
+  end
+
+  class APIError < Error
+    ERROR_CODE_CLASSES: Hash[String, singleton(APIError)]
+
+    def self.for: (code: String?, message: String?, ?status_code: Integer?) -> APIError
+  end
+
+  class UnauthorizedError < APIError
+  end
+
+  class ForbiddenError < APIError
+  end
+
+  class NotFoundError < APIError
+  end
+
+  class ValidationError < APIError
+  end
+
+  class ParameterMissingError < APIError
+  end
+
+  class ServerError < APIError
+  end
+
+  class Client
+    API_PREFIX: String
+    NETWORK_ERRORS: Array[singleton(Exception)]
+
+    attr_reader api_key: String
+    attr_reader base_url: String
+    attr_reader open_timeout: Integer
+    attr_reader read_timeout: Integer
+
+    def initialize: (api_key: String?, ?base_url: String?, ?open_timeout: Integer, ?read_timeout: Integer) -> void
+
+    def emails: () -> Emails
+    def templates: () -> Templates
+    def streams: () -> Streams
+    def stats: () -> Stats
+    def bounces: () -> Bounces
+    def dmarc: () -> Dmarc
+
+    def get: (String path, ?payload? query) -> response
+    def post: (String path, ?payload? body) -> response
+    def patch: (String path, ?payload? body) -> response
+  end
+
+  class Resource
+    attr_reader client: Client
+
+    def self.expose: (*Symbol names) -> void
+    def initialize: (?Client client) -> void
+  end
+
+  class Emails < Resource
+    def send: (payload params) -> response
+    def send_batch: (Array[payload] messages) -> response
+    def send_with_template: (payload params) -> response
+    def send_with_template_batch: (Array[payload] messages) -> response
+    def get: (Integer | String id) -> response
+    def list: (**untyped filters) -> response
+    def deliveries: (Integer | String id) -> response
+    def opens: (Integer | String id) -> response
+    def clicks: (Integer | String id) -> response
+    def raw: (Integer | String id) -> response
+
+    def self.send: (payload params) -> response
+    def self.send_batch: (Array[payload] messages) -> response
+    def self.send_with_template: (payload params) -> response
+    def self.send_with_template_batch: (Array[payload] messages) -> response
+    def self.get: (Integer | String id) -> response
+    def self.list: (**untyped filters) -> response
+    def self.deliveries: (Integer | String id) -> response
+    def self.opens: (Integer | String id) -> response
+    def self.clicks: (Integer | String id) -> response
+    def self.raw: (Integer | String id) -> response
+  end
+
+  class Templates < Resource
+    def list: () -> response
+    def create: (payload params) -> response
+    def get: (String permalink) -> response
+    def update: (String permalink, payload params) -> response
+    def archive: (String permalink) -> response
+    def render: (String permalink, ?payload template_model) -> response
+
+    def self.list: () -> response
+    def self.create: (payload params) -> response
+    def self.get: (String permalink) -> response
+    def self.update: (String permalink, payload params) -> response
+    def self.archive: (String permalink) -> response
+    def self.render: (String permalink, ?payload template_model) -> response
+  end
+
+  class Streams < Resource
+    def list: () -> response
+    def create: (payload params) -> response
+    def get: (String permalink) -> response
+    def update: (String permalink, payload params) -> response
+    def archive: (String permalink) -> response
+
+    def self.list: () -> response
+    def self.create: (payload params) -> response
+    def self.get: (String permalink) -> response
+    def self.update: (String permalink, payload params) -> response
+    def self.archive: (String permalink) -> response
+  end
+
+  class Stats < Resource
+    def get: (?from: String?, ?to: String?) -> response
+    def deliveries: () -> response
+
+    def self.get: (?from: String?, ?to: String?) -> response
+    def self.deliveries: () -> response
+  end
+
+  class Bounces < Resource
+    def list: (**untyped filters) -> response
+    def get: (Integer | String id) -> response
+
+    def self.list: (**untyped filters) -> response
+    def self.get: (Integer | String id) -> response
+  end
+
+  class Dmarc < Resource
+    def summary: (?domain: String?, ?from: String?, ?to: String?) -> response
+    def reports: (?domain: String?, ?from: String?, ?to: String?, ?page: Integer?, ?per_page: Integer?) -> response
+    def report: (Integer | String id) -> response
+
+    def self.summary: (?domain: String?, ?from: String?, ?to: String?) -> response
+    def self.reports: (?domain: String?, ?from: String?, ?to: String?, ?page: Integer?, ?per_page: Integer?) -> response
+    def self.report: (Integer | String id) -> response
+  end
+
+  class Mailer
+    IGNORED_HEADERS: Array[String]
+
+    attr_accessor settings: Hash[Symbol, untyped]
+
+    def initialize: (?Hash[Symbol, untyped]? settings) -> void
+    def deliver!: (untyped mail) -> response
+    def build_params: (untyped mail) -> payload
+  end
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: camelmailer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Camelmailer contributors
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-13 00:00:00.000000000 Z
+dependencies: []
+description: Ruby SDK for the Camelmailer transactional email API — send messages,
+  manage templates, streams and stats, and plug into Rails via the :camelmailer ActionMailer
+  delivery method.
+email:
+- hello@camelmailer.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CONTRIBUTING.md
+- LICENSE
+- README.md
+- lib/camelmailer.rb
+- lib/camelmailer/bounces.rb
+- lib/camelmailer/client.rb
+- lib/camelmailer/dmarc.rb
+- lib/camelmailer/emails.rb
+- lib/camelmailer/errors.rb
+- lib/camelmailer/mailer.rb
+- lib/camelmailer/railtie.rb
+- lib/camelmailer/resource.rb
+- lib/camelmailer/stats.rb
+- lib/camelmailer/streams.rb
+- lib/camelmailer/templates.rb
+- lib/camelmailer/version.rb
+- sig/camelmailer.rbs
+homepage: https://camelmailer.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://camelmailer.com
+  source_code_uri: https://github.com/camelmailer/camelmailer-ruby
+  changelog_uri: https://github.com/camelmailer/camelmailer-ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://camelmailer.com/docs
+  bug_tracker_uri: https://github.com/camelmailer/camelmailer-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.1'
+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: The Ruby and Rails SDK for Camelmailer
+test_files: []