coss-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3ecae82b15bffcfb63e8c7caa4871128f57256006afa3a7c2db264211c74a5bb
+  data.tar.gz: f1a21cfd38cdd9a3276dbde2028d75d8a3a00b06c6b2227f1a3451cbbd00c12e
+SHA512:
+  metadata.gz: 657b8a2f826b6bcce227f8274471bbda62a161ca174c2ae02ada26d3a9d8c567a854ed616e95785ec45926e47a5ef9531f1c80d7cecac6320e30cc0dd2c451a2
+  data.tar.gz: c5b184a8880696688ddf0c319e6df7b4103d55d57f56ab3627b3fa169356798ca5e6d781848de51dc5c91442a400c6011784bee144d5a485103998fbd11abb25

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release: the `:coss` Action Mailer delivery method, `coss(...)` in mailers for
+  coss.com's own fields (category, tags, scheduled sends, tracking, idempotency keys), and
+  `message.coss_email` with the email coss.com accepted.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cal.com, Inc.
+
+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,101 @@
+# coss-rails
+
+An Action Mailer delivery method that sends your Rails app's emails through the
+[coss.com](https://coss.com) API. Switch by changing configuration, not call sites.
+
+Rails 7.2–8.1, Ruby 3.2+. Docs: [coss.com/docs/integrations/rails](https://coss.com/docs/integrations/rails).
+
+## Install
+
+```ruby
+# Gemfile
+gem "coss-rails"
+```
+
+## Configure
+
+```ruby
+# config/environments/production.rb
+config.action_mailer.delivery_method = :coss
+config.action_mailer.coss_settings = {
+  api_key: Rails.application.credentials.coss_api_key, # default: ENV["COSS_API_KEY"]
+}
+```
+
+| Setting           | Default                 |                                                                  |
+| ----------------- | ----------------------- | ---------------------------------------------------------------- |
+| `api_key`         | `ENV["COSS_API_KEY"]`   | A missing key fails the delivery (`Coss::Rails::ConfigurationError`), never the boot. |
+| `base_url`        | `ENV["COSS_BASE_URL"]`, else `https://api.coss.com` |                                   |
+| `timeout`         | `30`                    | Seconds per attempt (Net::HTTP's open, read and write timeouts). |
+| `max_retries`     | `2`                     | Network errors, timeouts, 409, 429 and 5xx are retried with backoff (and `Retry-After`), with the same `Idempotency-Key`. |
+| `return_response` | `false`                 | Makes `deliver_now!` return the email coss.com accepted (see below). |
+
+The Railtie registers `:coss` before Action Mailer applies `config.action_mailer.*`. Without
+Rails, call `Coss::Rails.install(ActionMailer::Base)`, or use the delivery method with Mail
+directly: `mail.delivery_method Coss::Rails::DeliveryMethod, api_key: "coss_live_…"`.
+
+## Send
+
+Mailers stay as they are: from, to, cc, bcc, reply-to, subject, the text and HTML bodies,
+attachments (`attachments[...]` and `attachments.inline[...]`, referenced as
+`attachments["logo.png"].url`) and custom headers (`headers["X-Campaign"] = "spring"`) all go
+through. `deliver_later` works as usual.
+
+### coss.com options
+
+The Railtie adds `coss(...)` to every mailer (it includes `Coss::Rails::Mailer` into
+`ActionMailer::Base`). Call it in an action:
+
+```ruby
+class ReceiptMailer < ApplicationMailer
+  def receipt(order)
+    coss category: "receipts",
+         tags: { plan: order.plan },                  # or [{ name: "plan", value: "pro" }]
+         scheduled_at: 1.hour.from_now,               # Time/DateTime/TimeWithZone (sent as UTC) or a String
+         tracking: { opens: true, clicks: false },
+         idempotency_key: "receipt-#{order.id}"       # default: a random key per message
+    mail to: order.email, subject: "Your receipt"
+  end
+end
+```
+
+The options are stored on the message (`message.coss_options`), so they survive `deliver_later`
+(the job runs the action again). A later `coss` call replaces the options it gives; unknown
+options raise `ArgumentError`.
+
+### What a delivery returns
+
+```ruby
+message = ReceiptMailer.receipt(order).deliver_now
+message.coss_email # => { "object" => "email", "id" => "email_01k…", "status" => "queued", … }
+```
+
+With `return_response: true`, `deliver_now!` (and `Mail::Message#deliver!`) return that Hash
+instead of the message. (`deliver_now` always returns the message: that is Action Mailer's.)
+
+## Errors
+
+Everything this gem raises is a `Coss::Rails::Error`; `raise_delivery_errors` decides, as for any
+delivery method, whether `deliver_now` raises it.
+
+- `Coss::Rails::DeliveryError`: coss.com refused the email or couldn't be reached. Readers: `type`
+  (`invalid_request_error`, `authentication_error`, `permission_error`, `not_found_error`,
+  `idempotency_error`, `rate_limit_error`, `billing_error`, `api_error`, or `connection_error` /
+  `timeout_error` without a response), `code` (e.g. `domain_not_verified`), `status` (`nil` without
+  a response), `request_id` (`req_…`, quote it to support), `param`, `issues` and
+  `error_message`. Its message reads
+  `coss.com could not send the email: <message> (<code>)`.
+- `Coss::Rails::UnsupportedMessageError`: the message uses something coss.com can't send, so it
+  isn't sent at all: a `Sender` header, Return-Path or SMTP envelope (`smtp_envelope_from`,
+  `smtp_envelope_to`) other than the From address and recipients, no To address, a header given
+  more than once, or a part that is
+  neither the text body, the one HTML body nor an attachment (e.g. a `text/calendar`
+  alternative; attach invites instead).
+- `Coss::Rails::ConfigurationError`: no API key.
+
+Headers coss.com sets itself (`Date`, `Message-ID`, `MIME-Version`, `Content-Type`, …) are
+dropped. Non-ASCII header values are sent as RFC 2047 encoded-words.
+
+## License
+
+MIT

data/lib/coss/rails/client.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "securerandom"
+require "time"
+require "uri"
+
+module Coss
+  module Rails
+    # A small client for `POST /v1/emails`: auth + JSON, a timeout per attempt, retries with
+    # backoff (`integrations/README.md`, "Retries"), and every failure raised as a DeliveryError.
+    class Client
+      DEFAULT_BASE_URL = "https://api.coss.com"
+      DEFAULT_TIMEOUT = 30
+      DEFAULT_MAX_RETRIES = 2
+      API_VERSION = "2026-10-10"
+      USER_AGENT = "coss-rails/#{VERSION}".freeze
+
+      INITIAL_RETRY_DELAY_MS = 500
+      MAX_RETRY_DELAY_MS = 8_000
+      # A server asking us to wait longer than this gets its error returned instead of a stalled send.
+      MAX_RETRY_AFTER_MS = 60_000
+
+      TIMEOUT_ERRORS = [Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout, Timeout::Error].freeze
+      NETWORK_ERRORS = [
+        SocketError, SystemCallError, IOError, EOFError, OpenSSL::SSL::SSLError, Net::HTTPBadResponse,
+        Net::ProtocolError
+      ].freeze
+
+      # The response of one attempt: `status` (Integer), `headers` (lowercase names → values) and
+      # `body` (String).
+      Response = Struct.new(:status, :headers, :body, keyword_init: true)
+
+      # The default transport: one Net::HTTP connection per attempt.
+      class NetHttpTransport
+        # Sends one POST and returns a Response. Raises Net::HTTP's own errors (timeouts, network).
+        def call(uri:, headers:, body:, timeout:)
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = uri.scheme == "https"
+          http.open_timeout = timeout
+          http.read_timeout = timeout
+          http.write_timeout = timeout
+          http.max_retries = 0
+          request = Net::HTTP::Post.new(uri.request_uri, headers)
+          request.body = body
+          response = http.start { |connection| connection.request(request) }
+          Response.new(
+            status: response.code.to_i,
+            headers: response.each_header.to_h { |name, value| [name.downcase, value] },
+            body: response.body.to_s
+          )
+        end
+      end
+
+      attr_reader :base_url, :timeout, :max_retries
+
+      # - `api_key`: required.
+      # - `base_url`: defaults to `https://api.coss.com` (trailing slashes trimmed).
+      # - `timeout`: seconds per attempt (Net::HTTP's open, read and write timeouts), default 30.
+      # - `max_retries`: default 2, so at most 3 attempts.
+      # - `sleep`: called with the wait before a retry **in seconds** (a Float), like `Kernel#sleep`.
+      # - `random`: returns a Float in [0, 1) for the backoff's jitter.
+      # - `transport`: responds to `call(uri:, headers:, body:, timeout:)` and returns a Response.
+      def initialize(api_key:, base_url: nil, timeout: nil, max_retries: nil, sleep: nil, random: nil, transport: nil)
+        @api_key = api_key
+        @base_url = (base_url || DEFAULT_BASE_URL).to_s.sub(%r{/+\z}, "")
+        @timeout = timeout || DEFAULT_TIMEOUT
+        @max_retries = Integer(max_retries || DEFAULT_MAX_RETRIES)
+        @sleep = sleep || ->(seconds) { Kernel.sleep(seconds) }
+        @random = random || -> { Kernel.rand }
+        @transport = transport || NetHttpTransport.new
+      end
+
+      # Sends one email (`body`: the request as a Hash) and returns the API's email as a Hash.
+      # `idempotency_key` defaults to a random UUID; every attempt reuses it.
+      def send_email(body, idempotency_key: nil)
+        key = idempotency_key || SecureRandom.uuid
+        check_header_value!("Idempotency-Key", key)
+        headers = {
+          "Authorization" => "Bearer #{@api_key}",
+          "Content-Type" => "application/json",
+          "Accept" => "application/json",
+          "Coss-Version" => API_VERSION,
+          "User-Agent" => USER_AGENT,
+          "Idempotency-Key" => key
+        }
+        check_header_value!("Authorization", headers["Authorization"])
+        request(URI("#{@base_url}/v1/emails"), headers, JSON.generate(body))
+      end
+
+      # Exponential backoff (500 ms, 1 s, 2 s … capped at 8 s) minus up to 25% random jitter, in ms.
+      def self.backoff_delay(retry_index, random)
+        delay = [INITIAL_RETRY_DELAY_MS * (2**retry_index), MAX_RETRY_DELAY_MS].min
+        delay * (1 - (random * 0.25))
+      end
+
+      # `Retry-After` in milliseconds: delay-seconds or an HTTP date; `nil` when absent or invalid.
+      def self.parse_retry_after(value, now: Time.now)
+        trimmed = value.to_s.strip
+        return nil if trimmed.empty?
+
+        seconds = Float(trimmed, exception: false)
+        return (seconds >= 0 ? seconds * 1000 : nil) if seconds&.finite?
+
+        date = parse_http_date(trimmed)
+        date && [0, (date - now) * 1000].max
+      end
+
+      def self.parse_http_date(value)
+        Time.httpdate(value)
+      rescue ArgumentError
+        begin
+          Time.rfc2822(value)
+        rescue ArgumentError
+          nil
+        end
+      end
+      private_class_method :parse_http_date
+
+      # 409 (an idempotent request still in progress), 429 and 5xx are transient.
+      def self.retryable_status?(status)
+        status == 409 || status == 429 || status >= 500
+      end
+
+      private
+
+      def request(uri, headers, body)
+        retry_index = 0
+        loop do
+          error, result, retryable, retry_after_ms = attempt(uri, headers, body)
+          return result unless error
+          raise error if !retryable || retry_index >= @max_retries
+
+          delay = retry_after_ms || self.class.backoff_delay(retry_index, @random.call)
+          raise error if delay > MAX_RETRY_AFTER_MS
+
+          @sleep.call(delay / 1000.0)
+          retry_index += 1
+        end
+      end
+
+      # Returns `[error, result, retryable, retry_after_ms]`.
+      def attempt(uri, headers, body)
+        begin
+          response = @transport.call(uri: uri, headers: headers, body: body, timeout: @timeout)
+        rescue *TIMEOUT_ERRORS
+          return [timeout_error, nil, true, nil]
+        rescue *NETWORK_ERRORS => e
+          return [network_error(e), nil, true, nil]
+        end
+
+        request_id = response.headers["x-request-id"]
+        text = Mime.utf8(response.body)
+        unless (200..299).cover?(response.status)
+          return [
+            error_from_response(response.status, text, request_id),
+            nil,
+            self.class.retryable_status?(response.status),
+            self.class.parse_retry_after(response.headers["retry-after"])
+          ]
+        end
+
+        begin
+          [nil, JSON.parse(text), false, nil]
+        rescue JSON::ParserError
+          error = DeliveryError.new(
+            type: "api_error",
+            code: "invalid_response",
+            message: "The coss.com API returned an HTTP #{response.status} response that is not valid JSON.",
+            status: response.status,
+            request_id: request_id
+          )
+          [error, nil, false, nil]
+        end
+      end
+
+      def error_from_response(status, text, header_request_id)
+        envelope = begin
+          parsed = JSON.parse(text)
+          parsed.is_a?(Hash) ? parsed["error"] : nil
+        rescue JSON::ParserError
+          nil
+        end
+
+        unless envelope.is_a?(Hash) && envelope["message"].is_a?(String)
+          return DeliveryError.new(
+            type: "api_error",
+            code: "unexpected_response",
+            message: "The coss.com API returned an unexpected HTTP #{status} response.",
+            status: status,
+            request_id: header_request_id
+          )
+        end
+
+        type = envelope["type"]
+        DeliveryError.new(
+          type: DeliveryError::API_ERROR_TYPES.include?(type) ? type : "api_error",
+          code: envelope["code"].is_a?(String) ? envelope["code"] : "unknown_error",
+          message: envelope["message"],
+          status: status,
+          request_id: envelope["request_id"].is_a?(String) ? envelope["request_id"] : header_request_id,
+          param: envelope["param"].is_a?(String) ? envelope["param"] : nil,
+          issues: parse_issues(envelope["issues"])
+        )
+      end
+
+      def parse_issues(value)
+        return nil unless value.is_a?(Array)
+
+        value.filter_map do |issue|
+          next unless issue.is_a?(Hash) && issue["path"].is_a?(String) && issue["message"].is_a?(String)
+
+          { "path" => issue["path"], "message" => issue["message"] }
+        end
+      end
+
+      def timeout_error
+        DeliveryError.new(
+          type: "timeout_error",
+          code: "request_timeout",
+          message: "Request timed out after #{@timeout} seconds."
+        )
+      end
+
+      def network_error(cause)
+        DeliveryError.new(
+          type: "connection_error",
+          code: "network_error",
+          message: "Could not reach the coss.com API at #{@base_url}: #{cause.message} (#{cause.class})"
+        )
+      end
+
+      # Net::HTTP refuses (or mangles) header values with line breaks or non-ASCII bytes; fail
+      # before sending instead of with an error that looks like a network failure.
+      def check_header_value!(name, value)
+        return if value.is_a?(String) && value.match?(/\A[ -~]*\z/)
+
+        raise DeliveryError.new(
+          type: "invalid_request_error",
+          code: "invalid_header",
+          message: "Invalid request header: #{name} must be printable ASCII."
+        )
+      end
+    end
+  end
+end

data/lib/coss/rails/delivery_method.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Coss
+  module Rails
+    # The `:coss` Action Mailer delivery method (also usable with Mail directly:
+    # `mail.delivery_method Coss::Rails::DeliveryMethod, api_key: "…"`).
+    #
+    # Settings (`config.action_mailer.coss_settings`):
+    #
+    # - `api_key`: defaults to `ENV["COSS_API_KEY"]`; a missing key fails the delivery, not the boot.
+    # - `base_url`: defaults to `https://api.coss.com`.
+    # - `timeout`: seconds per attempt, default 30.
+    # - `max_retries`: default 2.
+    # - `return_response`: when true, `deliver_now!` / `Mail::Message#deliver!` return the email Hash.
+    #
+    # `sleep`, `random` and `transport` are passed to Client (for tests).
+    class DeliveryMethod
+      CLIENT_SETTINGS = %i[base_url timeout max_retries sleep random transport].freeze
+
+      attr_accessor :settings
+
+      def initialize(settings = {})
+        @settings = (settings || {}).to_h.transform_keys(&:to_sym)
+      end
+
+      # Sends `mail` and returns the email as the API returned it (a Hash), also stored as
+      # `mail.coss_email`. Raises UnsupportedMessageError, ConfigurationError or DeliveryError.
+      def deliver!(mail)
+        body, idempotency_key = MessageMapper.new(mail).to_request
+        email = client.send_email(body, idempotency_key: idempotency_key)
+        mail.coss_email = email
+        email
+      end
+
+      private
+
+      def client
+        options = settings.slice(*CLIENT_SETTINGS)
+        base_url = ENV.fetch("COSS_BASE_URL", nil)
+        options[:base_url] = base_url if options[:base_url].to_s.empty? && !base_url.to_s.empty?
+        Client.new(api_key: api_key, **options)
+      end
+
+      def api_key
+        key = settings[:api_key]
+        key = ENV.fetch("COSS_API_KEY", nil) if key.nil? || key.to_s.empty?
+        return key unless key.nil? || key.empty?
+
+        raise ConfigurationError,
+              "No coss.com API key: set config.action_mailer.coss_settings[:api_key] " \
+              "(coss_settings[:api_key]) or the COSS_API_KEY environment variable."
+      end
+    end
+  end
+end

data/lib/coss/rails/errors.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Coss
+  module Rails
+    # The base of every error this gem raises: `rescue Coss::Rails::Error` catches them all.
+    class Error < StandardError; end
+
+    # The delivery method isn't configured (no API key).
+    class ConfigurationError < Error; end
+
+    # The message uses something coss.com can't send (a `Sender` header, a separate envelope, a
+    # header given twice, an alternative part other than one HTML part …). Raised before any request.
+    class UnsupportedMessageError < Error; end
+
+    # coss.com refused the email, or couldn't be reached.
+    class DeliveryError < Error
+      # The API's error types; anything else a response says becomes `api_error`.
+      API_ERROR_TYPES = %w[
+        invalid_request_error authentication_error permission_error not_found_error
+        idempotency_error rate_limit_error billing_error api_error
+      ].freeze
+
+      # `invalid_request_error`, `authentication_error`, … or, without a response,
+      # `connection_error` / `timeout_error`.
+      attr_reader :type
+      # Machine-readable reason, e.g. `domain_not_verified`.
+      attr_reader :code
+      # The HTTP status, `nil` when there was no response (network error, timeout).
+      attr_reader :status
+      # The API's request id (`req_…`) to quote to support, `nil` when unknown.
+      attr_reader :request_id
+      # The request parameter the error is about, when the API names one.
+      attr_reader :param
+      # Validation issues, `[{ "path" => "to", "message" => "…" }]`, when the API gives them.
+      attr_reader :issues
+      # The API's own message (without this gem's prefix).
+      attr_reader :error_message
+
+      def initialize(type:, code:, message:, status: nil, request_id: nil, param: nil, issues: nil)
+        @type = type
+        @code = code
+        @error_message = message
+        @status = status
+        @request_id = request_id
+        @param = param
+        @issues = issues
+        details = issues&.map { |issue| "#{issue['path']}: #{issue['message']}" }&.join("; ")
+        text = "coss.com could not send the email: #{message} (#{code})"
+        text += " #{details}" if details && !details.empty?
+        super(text)
+      end
+
+      # The error as the API's envelope fields (`param` and `issues` only when present).
+      def to_h
+        hash = { "type" => type, "code" => code, "message" => error_message, "status" => status,
+                 "request_id" => request_id }
+        hash["param"] = param unless param.nil?
+        hash["issues"] = issues unless issues.nil?
+        hash
+      end
+    end
+  end
+end

data/lib/coss/rails/mailer.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Coss
+  module Rails
+    # Adds `coss(...)` to Action Mailer mailers (the Railtie includes it into `ActionMailer::Base`).
+    #
+    #   class ReceiptMailer < ApplicationMailer
+    #     def receipt(order)
+    #       coss category: "receipts", tags: { plan: order.plan }, idempotency_key: "receipt-#{order.id}"
+    #       mail to: order.email, subject: "Your receipt"
+    #     end
+    #   end
+    #
+    # The options are stored on the message (`message.coss_options`), so they survive
+    # `deliver_later`: the job runs the action again.
+    module Mailer
+      # Sets coss.com's fields for the message this action builds. Calling it again merges: a
+      # later call replaces the options it gives. Raises ArgumentError for invalid values.
+      #
+      # - `category`: what kind of email this is, e.g. `"marketing"`.
+      # - `tags`: `{ plan: "pro" }` or `[{ name: "plan", value: "pro" }]`.
+      # - `scheduled_at`: a Time, DateTime or ActiveSupport::TimeWithZone (sent as UTC), or an
+      #   ISO 8601 String sent as given; at most 30 days ahead.
+      # - `tracking`: `{ opens: true, clicks: false }`.
+      # - `idempotency_key`: sent as `Idempotency-Key` (default: a random key per message).
+      def coss(category: nil, tags: nil, scheduled_at: nil, tracking: nil, idempotency_key: nil)
+        given = Options.normalize(
+          category: category, tags: tags, scheduled_at: scheduled_at, tracking: tracking,
+          idempotency_key: idempotency_key
+        )
+        message.coss_options = message.coss_options.merge(given)
+      end
+    end
+  end
+end

data/lib/coss/rails/message.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Coss
+  module Rails
+    # Adds coss.com's accessors to `Mail::Message`.
+    module MessageExtension
+      # The email as the coss.com API returned it (a Hash: `"id" => "email_…"`, `"status"`, …),
+      # set once the message is delivered.
+      attr_accessor :coss_email
+
+      # coss.com's fields for this message (`category`, `tags`, `scheduled_at`, `tracking`,
+      # `idempotency_key`), normally set with `coss(...)` in a mailer action.
+      def coss_options
+        @coss_options ||= {}
+      end
+
+      def coss_options=(options)
+        @coss_options = options.nil? ? {} : Options.normalize(options)
+      end
+    end
+
+    ::Mail::Message.include(MessageExtension)
+  end
+end

data/lib/coss/rails/message_mapper.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+module Coss
+  module Rails
+    # Turns a `Mail::Message` into the `POST /v1/emails` body (`integrations/README.md`,
+    # "The message"), refusing what coss.com can't send.
+    class MessageMapper
+      # Headers read into the body's own fields (all reserved by the API as headers too).
+      ADDRESS_FIELDS = { to: :to, cc: :cc, bcc: :bcc, reply_to: :reply_to }.freeze
+      # Not sent as custom headers: the part's own Content-ID at the top level (single-part messages).
+      SKIPPED_HEADERS = %w[content-id].freeze
+      BODY_TYPES = %w[text/plain text/html].freeze
+
+      def initialize(mail)
+        @mail = mail
+      end
+
+      # Returns `[body, idempotency_key]`; `idempotency_key` is nil unless the message sets one.
+      def to_request
+        refuse_unsupported_envelope!
+        options = Options.normalize(@mail.coss_options || {})
+
+        to = addresses(:to)
+        if to.empty?
+          refuse!("a message without a To address",
+                  "coss.com needs at least one and never moves Cc or Bcc addresses into To")
+        end
+        body = { "from" => from, "to" => to }
+        %i[cc bcc reply_to].each { |field| put(body, field.to_s, addresses(field)) }
+        body["subject"] = Mime.utf8(@mail.subject.to_s)
+        html, text, attachments = contents
+        put(body, "html", html)
+        put(body, "text", text)
+        put(body, "attachments", attachments)
+        put(body, "headers", custom_headers)
+        %i[category tags scheduled_at tracking].each { |key| put(body, key.to_s, options[key]) }
+
+        [body, options[:idempotency_key]]
+      end
+
+      private
+
+      # Sets `body[key]` unless `value` is nil or empty: empty fields are left out.
+      def put(body, key, value)
+        body[key] = value unless value.nil? || (value.respond_to?(:empty?) && value.empty?)
+      end
+
+      def refuse!(what, instead)
+        raise UnsupportedMessageError, "coss-rails: #{what} can't be sent through coss.com; #{instead}."
+      end
+
+      # --- addresses ---------------------------------------------------------------------------
+
+      def address_list(name)
+        field = @mail.header[name]
+        return [] if field.nil?
+
+        if field.is_a?(Array)
+          refuse!("a `#{field.first.name}` header given more than once", "give one header with every address")
+        end
+        unless field.respond_to?(:addrs)
+          refuse!("a `#{field.name}` header that isn't a valid address list", "fix its addresses")
+        end
+
+        field.addrs
+      end
+
+      def addresses(name)
+        address_list(name).filter_map do |address|
+          next if address.address.nil? || address.address.empty?
+
+          Mime.format_address(Mime.utf8(address.address), address.display_name)
+        end
+      end
+
+      def from
+        list = address_list(:from)
+        raise UnsupportedMessageError, "coss-rails: the message has no From address." if list.empty?
+
+        refuse!("more than one From address", "send from one address") if list.size > 1
+
+        Mime.format_address(Mime.utf8(list.first.address), list.first.display_name)
+      end
+
+      # A Sender naming the From address is harmless (dropped like other reserved headers).
+      def refuse_foreign_sender!
+        sender = @mail.header[:sender] && @mail.sender
+        return if sender.nil? || sender.to_s.empty? || sender.to_s.downcase == from_address
+
+        refuse!("a `Sender` header other than the From address",
+                "coss.com sets the Sender itself; set `from` instead")
+      end
+
+      def from_address
+        @from_address ||= address_list(:from).first&.address.to_s.downcase
+      end
+
+      # --- envelope ----------------------------------------------------------------------------
+
+      def refuse_unsupported_envelope!
+        refuse_foreign_sender!
+
+        return_path = @mail.return_path
+        if return_path && !return_path.to_s.empty? && return_path.to_s.downcase != from_address
+          refuse!("a Return-Path other than the From address", "coss.com handles bounces itself")
+        end
+
+        # Mail derives the envelope from the headers unless it was set explicitly (an instance
+        # variable of its own; the readers can't tell an explicit value from the default).
+        envelope_from = @mail.instance_variable_get(:@smtp_envelope_from)
+        if envelope_from && envelope_address(envelope_from) != from_address
+          refuse!("an SMTP envelope sender other than the From address", "coss.com sends from the From address")
+        end
+
+        envelope_to = @mail.instance_variable_get(:@smtp_envelope_to)
+        return unless envelope_to
+
+        given = Array(envelope_to).map { |address| envelope_address(address) }.uniq.sort
+        destinations = Array(@mail.destinations).map { |address| address.to_s.downcase }.uniq.sort
+        return if given == destinations
+
+        refuse!("SMTP envelope recipients other than to + cc + bcc", "coss.com sends to the message's recipients")
+      end
+
+      def envelope_address(value)
+        string = value.to_s
+        address = string.include?("<") ? Mail::Address.new(string).address : string
+        address.to_s.strip.downcase
+      rescue Mail::Field::ParseError
+        string.strip.downcase
+      end
+
+      # --- bodies and attachments --------------------------------------------------------------
+
+      # `[html, text, attachments]` from the message's leaf parts (the message itself when it is
+      # single-part). Anything that is neither the one text part, the one HTML part nor an
+      # attachment is refused.
+      def contents
+        html = nil
+        text = nil
+        attachments = []
+        leaves(@mail).each do |part|
+          if attachment?(part)
+            attachments << attachment(part, attachments.size + 1)
+            next
+          end
+
+          case part.mime_type&.downcase
+          when nil, "text/plain"
+            refuse!("a second text/plain part", "send one text and one HTML body") unless text.nil?
+            text = body_text(part)
+          when "text/html"
+            refuse!("a second text/html part", "send one HTML body") unless html.nil?
+            html = body_text(part)
+          else
+            refuse!("a #{part.mime_type} part that isn't an attachment",
+                    "send one text and one HTML body, and attach anything else")
+          end
+        end
+        [html, text, attachments]
+      end
+
+      # Mail only sets a multipart Content-Type when it encodes the message, so a message with
+      # parts counts as multipart whatever its header says so far.
+      def leaves(part)
+        return (part.multipart? ? [] : [part]) if part.parts.empty?
+
+        # A multipart attachment (an attached multipart/mixed tree) would otherwise be taken
+        # apart below and its text sent as the email's body.
+        refuse!("a multipart attachment", "attach its files one by one") if !part.equal?(@mail) && attachment?(part)
+        part.parts.flat_map { |child| leaves(child) }
+      end
+
+      def attachment?(part)
+        return true if part.attachment?
+
+        disposition = disposition_type(part)
+        return true if disposition == "attachment"
+
+        (disposition == "inline" || content_id?(part)) && !BODY_TYPES.include?(part.mime_type&.downcase)
+      end
+
+      def disposition_type(part)
+        field = part.header[:content_disposition]
+        field.respond_to?(:disposition_type) ? field.disposition_type.to_s.downcase : nil
+      end
+
+      def body_text(part)
+        Mime.utf8(part.decoded)
+      end
+
+      def attachment(part, position)
+        filename = part.filename
+        params = {
+          "filename" => filename.nil? || filename.to_s.empty? ? "attachment-#{position}" : Mime.utf8(filename),
+          # The bytes as sent: body.decoded undoes the transfer encoding without transcoding text.
+          "content" => Mime.base64(part.body.decoded)
+        }
+        content_type = Mime.media_type(part.mime_type)
+        params["content_type"] = content_type if content_type
+        content_id = content_id(part)
+        params["content_id"] = content_id if content_id
+        params
+      end
+
+      def content_id(part)
+        if disposition_type(part) == "inline" && !content_id?(part) && part.respond_to?(:add_content_id)
+          # Mail would generate one when encoding the message; do it now so it can be referenced.
+          part.add_content_id
+        end
+        content_id?(part) ? Mime.bare_content_id(part.header[:content_id].value) : nil
+      end
+
+      def content_id?(part)
+        !part.header[:content_id].nil?
+      end
+
+      # --- headers -----------------------------------------------------------------------------
+
+      def custom_headers
+        headers = {}
+        seen = {}
+        @mail.header.fields.each do |field|
+          name = field.name.to_s.strip
+          lower = name.downcase
+          next if name.empty? || Mime.reserved_header?(name) || SKIPPED_HEADERS.include?(lower)
+
+          value = header_value(field)
+          refuse!("the `#{name}` header given more than once", "coss.com sends each header once") if seen[lower]
+          seen[lower] = true
+
+          encoded = Mime.encode_header_value(value)
+          headers[name] = encoded unless encoded.empty?
+        end
+        headers
+      end
+
+      # The value as the app gave it (before Mail's encoding), so the README's encoding applies.
+      def header_value(field)
+        value = field.unparsed_value
+        if value.is_a?(Array)
+          refuse!("the `#{field.name}` header with several values", "coss.com sends each header once") if value.size > 1
+          value = value.first
+        end
+        value = field.decoded if value.nil? && field.respond_to?(:decoded)
+        Mime.utf8(value.to_s)
+      end
+    end
+  end
+end

data/lib/coss/rails/mime.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Coss
+  module Rails
+    # The message helpers every coss.com driver shares (`integrations/README.md`, "The message"),
+    # mirroring `packages/sdk/src/core/mime.ts`.
+    module Mime
+      # Headers the API refuses because coss.com or the provider sets them (`RESERVED_HEADERS` in
+      # `packages/email/src/schemas.ts`). Mail sets several on every message, so they are dropped.
+      RESERVED_HEADERS = %w[
+        from to cc bcc reply-to subject sender return-path date message-id mime-version
+        content-type content-transfer-encoding content-disposition dkim-signature received
+      ].freeze
+
+      # RFC 5322 specials (minus "."): the API refuses them in an unquoted display name.
+      NAME_SPECIALS = /["<>,;:@()\[\]\\]/
+
+      PRINTABLE_ASCII = /\A[ -~]*\z/
+
+      # One encoded-word holds at most 75 characters: `=?UTF-8?B?` + base64 + `?=` leaves 63 for
+      # the base64, i.e. 45 bytes of UTF-8 (rounded down to whole characters).
+      ENCODED_WORD_BYTES = 45
+
+      # What JavaScript's `String#trim` removes (Ruby's `strip` only knows ASCII whitespace).
+      TRIM_LEADING = /\A[[:space:]\u{FEFF}]+/
+      TRIM_TRAILING = /[[:space:]\u{FEFF}]+\z/
+
+      module_function
+
+      # Whether the API would refuse a custom header with this name.
+      def reserved_header?(name)
+        lower = name.to_s.downcase
+        RESERVED_HEADERS.include?(lower) || lower.start_with?("x-ses-")
+      end
+
+      # `addr`, or `Name <addr>` with the name quoted when it needs to be.
+      def format_address(address, name = nil)
+        trimmed = name.nil? ? "" : trim(utf8(name))
+        return address if trimmed.empty?
+
+        display = if NAME_SPECIALS.match?(trimmed)
+                    %("#{trimmed.gsub(/["\\]/) { |char| "\\#{char}" }}")
+                  else
+                    trimmed
+                  end
+        "#{display} <#{address}>"
+      end
+
+      # A header value as the API takes it: one line of printable ASCII. Folded lines are unfolded,
+      # other control characters become spaces, and anything non-ASCII becomes RFC 2047
+      # encoded-words (`=?UTF-8?B?…?=`). Returns `""` for a value that ends up empty.
+      def encode_header_value(value)
+        unfolded = trim(utf8(value.to_s).gsub(/\r?\n[ \t]*/, " ").gsub(/\p{Cc}/, " "))
+        return unfolded if PRINTABLE_ASCII.match?(unfolded)
+
+        words = []
+        chunk = +"".b
+        unfolded.each_char do |char|
+          if chunk.bytesize + char.bytesize > ENCODED_WORD_BYTES
+            words << encoded_word(chunk)
+            chunk = +"".b
+          end
+          chunk << char.b
+        end
+        words << encoded_word(chunk) unless chunk.empty?
+        words.join(" ")
+      end
+
+      # Standard, padded base64 without line breaks.
+      def base64(bytes)
+        [bytes.to_s].pack("m0")
+      end
+
+      # `type/subtype` without parameters, lowercase (`text/plain; charset=utf-8` → `text/plain`),
+      # `nil` when there is none.
+      def media_type(content_type)
+        type = content_type.to_s.split(";").first.to_s.strip.downcase
+        type.empty? ? nil : type
+      end
+
+      # A Content-ID without its angle brackets (`<logo@acme>` → `logo@acme`), `nil` when empty.
+      def bare_content_id(content_id)
+        id = content_id.to_s.strip.delete_prefix("<").delete_suffix(">")
+        id.empty? ? nil : id
+      end
+
+      # `value` as a valid UTF-8 string: text in another known encoding is transcoded, bytes of
+      # unknown encoding (binary) are read as UTF-8, and invalid bytes are replaced.
+      def utf8(value)
+        string = value.to_s
+        if string.encoding == Encoding::BINARY
+          string = string.dup.force_encoding(Encoding::UTF_8)
+        elsif string.encoding != Encoding::UTF_8
+          string = string.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+        end
+        string.valid_encoding? ? string : string.scrub
+      end
+
+      def trim(string)
+        string.sub(TRIM_LEADING, "").sub(TRIM_TRAILING, "")
+      end
+
+      def encoded_word(bytes)
+        "=?UTF-8?B?#{base64(bytes)}?="
+      end
+      private_class_method :encoded_word
+    end
+  end
+end

data/lib/coss/rails/options.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Coss
+  module Rails
+    # coss.com's own fields for one message (`category`, `tags`, `scheduled_at`, `tracking`, the
+    # idempotency key), validated and turned into what the API takes.
+    module Options
+      KEYS = %i[category tags scheduled_at tracking idempotency_key].freeze
+
+      module_function
+
+      # Validates `options` (a Hash with `KEYS`) and returns them ready for the request body:
+      # `tags` as `[{ "name" => …, "value" => … }]`, `scheduled_at` as a UTC
+      # `YYYY-MM-DDTHH:MM:SSZ` string (a String is kept as given), `tracking` with string keys.
+      # `nil` values are left out. Raises ArgumentError for anything else.
+      def normalize(options)
+        raise ArgumentError, "coss.com options must be a Hash, got #{options.class}" unless options.is_a?(Hash)
+
+        unknown = options.keys.map(&:to_sym) - KEYS
+        unless unknown.empty?
+          raise ArgumentError, "unknown coss.com option(s): #{unknown.join(', ')} (known: #{KEYS.join(', ')})"
+        end
+
+        options.each_with_object({}) do |(key, value), normalized|
+          next if value.nil?
+
+          key = key.to_sym
+          normalized[key] = send(:"normalize_#{key}", value)
+        end
+      end
+
+      def normalize_category(value)
+        string(value, "category")
+      end
+
+      def normalize_idempotency_key(value)
+        string(value, "idempotency_key")
+      end
+
+      def normalize_tags(value)
+        case value
+        when Hash
+          value.map { |name, tag_value| tag(name, tag_value) }
+        when Array
+          value.map do |entry|
+            unless entry.is_a?(Hash)
+              raise ArgumentError, "coss.com tags must be a Hash or an Array of { name:, value: } Hashes"
+            end
+
+            tag(entry[:name] || entry["name"], entry[:value] || entry["value"])
+          end
+        else
+          raise ArgumentError, "coss.com tags must be a Hash or an Array of { name:, value: } Hashes"
+        end
+      end
+
+      def normalize_scheduled_at(value)
+        case value
+        when String
+          value
+        when DateTime
+          value.to_time.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
+        when Time
+          value.getutc.strftime("%Y-%m-%dT%H:%M:%SZ")
+        else
+          # ActiveSupport::TimeWithZone is_a?(Time) already; this covers other time-likes.
+          return value.utc.strftime("%Y-%m-%dT%H:%M:%SZ") if value.respond_to?(:utc) && !value.is_a?(Date)
+
+          raise ArgumentError,
+                "coss.com scheduled_at must be a Time, DateTime, ActiveSupport::TimeWithZone or String, " \
+                "got #{value.class}"
+        end
+      end
+
+      def normalize_tracking(value)
+        unless value.is_a?(Hash)
+          raise ArgumentError,
+                "coss.com tracking must be a Hash like { opens: true, clicks: false }"
+        end
+
+        value.to_h { |key, setting| [key.to_s, setting] }
+      end
+
+      def tag(name, value)
+        raise ArgumentError, "a coss.com tag needs a name and a value" if name.nil? || value.nil?
+
+        { "name" => name.to_s, "value" => value.to_s }
+      end
+
+      def string(value, field)
+        return value if value.is_a?(String)
+        return value.to_s if value.is_a?(Symbol)
+
+        raise ArgumentError, "coss.com #{field} must be a String, got #{value.class}"
+      end
+
+      private_class_method :normalize_category, :normalize_idempotency_key, :normalize_tags,
+                           :normalize_scheduled_at, :normalize_tracking, :tag, :string
+    end
+  end
+end

data/lib/coss/rails/railtie.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Coss
+  module Rails
+    # Registers `:coss` before Action Mailer applies `config.action_mailer.*`, so
+    # `config.action_mailer.coss_settings = { ... }` has somewhere to go.
+    class Railtie < ::Rails::Railtie
+      initializer "coss_rails.add_delivery_method", before: "action_mailer.set_configs" do
+        ActiveSupport.on_load(:action_mailer) { Coss::Rails.install(self) }
+      end
+    end
+  end
+end

data/lib/coss/rails/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Coss
+  module Rails
+    VERSION = "0.1.0"
+  end
+end

data/lib/coss/rails.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "mail"
+
+require_relative "rails/version"
+require_relative "rails/errors"
+require_relative "rails/mime"
+require_relative "rails/options"
+require_relative "rails/client"
+require_relative "rails/message"
+require_relative "rails/message_mapper"
+require_relative "rails/delivery_method"
+require_relative "rails/mailer"
+
+module Coss
+  # Sends Action Mailer messages through the coss.com API (`POST /v1/emails`).
+  #
+  #   # config/environments/production.rb
+  #   config.action_mailer.delivery_method = :coss
+  #   config.action_mailer.coss_settings = { api_key: ENV["COSS_API_KEY"] }
+  module Rails
+    # Registers the `:coss` delivery method on `base` (normally `ActionMailer::Base`) and adds
+    # `coss(...)` to its mailers. The Railtie calls this; call it yourself without Rails.
+    def self.install(base)
+      base.add_delivery_method(:coss, DeliveryMethod) unless base.delivery_methods.key?(:coss)
+      base.include(Mailer) unless base < Mailer
+      base
+    end
+  end
+end
+
+require_relative "rails/railtie" if defined?(Rails::Railtie)

data/lib/coss-rails.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "coss/rails"

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: coss-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Cal.com, Inc.
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionmailer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+description: Send your Rails app's Action Mailer emails through coss.com by changing
+  configuration, not call sites.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/coss-rails.rb
+- lib/coss/rails.rb
+- lib/coss/rails/client.rb
+- lib/coss/rails/delivery_method.rb
+- lib/coss/rails/errors.rb
+- lib/coss/rails/mailer.rb
+- lib/coss/rails/message.rb
+- lib/coss/rails/message_mapper.rb
+- lib/coss/rails/mime.rb
+- lib/coss/rails/options.rb
+- lib/coss/rails/railtie.rb
+- lib/coss/rails/version.rb
+homepage: https://coss.com/docs/integrations/rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://coss.com/docs/integrations/rails
+  source_code_uri: https://github.com/cosscom/coss/tree/main/integrations/rails
+  changelog_uri: https://github.com/cosscom/coss/blob/main/integrations/rails/CHANGELOG.md
+  bug_tracker_uri: https://github.com/cosscom/coss/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: An Action Mailer delivery method that sends through the coss.com API.
+test_files: []