mailtruss 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0aefd75093db988be98ed2ee2a5649567f768ea1a5506306fec9cf13dce5e161
+  data.tar.gz: 552f058e0408b3d83845ddd2ed98fb363f8bb7a0c734e1a526e0dee4f4eb89ba
+SHA512:
+  metadata.gz: 1ff4df3ef60ab13e0778b5c469459d126f33219431b0ec81f828191b368b3add7a8a657ab107ac35fdc7be81776924d5ccae693c2db44d7940081f235d0c02af
+  data.tar.gz: 890aeea078fbf44a6e0d4b875a10ee0618526656d622a9f554d884fb9c2c76a5e60b20918aadc2beb82e50c3ebe9f294cd08a0f9ac02646b9600a7dc19064c0f

data/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Mailtruss
+
+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,23 @@
+# mailtruss (Ruby)
+
+Ruby 3.0+ client for the [Mailtruss](https://mailtruss.com) email API, with a Rails ActionMailer delivery method. Standard library only.
+
+```ruby
+client = Mailtruss::Client.new(ENV.fetch("MAILTRUSS_API_KEY"))
+client.emails.send({ from: "hello@yourdomain.com", to: "ana@example.com", subject: "Welcome", html: "<p>Hi Ana</p>" }, idempotency_key: "welcome-ana")
+```
+
+Resources: `emails`, `domains`, `api_keys`, `contacts`, `segments`, `topics`, `suppressions`, `webhooks`, `templates`, `broadcasts` (`deliver` sends one), `logs`, `inbound`. Errors are `Mailtruss::Error` (`name`, `status`, `request_id`).
+
+## Rails
+
+With the gem in your Gemfile, `:mailtruss` is registered as a delivery method:
+
+```ruby
+config.action_mailer.delivery_method = :mailtruss
+config.action_mailer.mailtruss_settings = { api_key: ENV["MAILTRUSS_API_KEY"] }
+```
+
+Webhooks: `event = Mailtruss.verify_webhook(request.raw_post, request.headers, ENV.fetch("MAILTRUSS_WEBHOOK_SECRET"))`.
+
+Tests: `ruby -Ilib test/test_mailtruss.rb` (needs the `mail` and `minitest` gems).

data/lib/mailtruss/delivery_method.rb

@@ -0,0 +1,60 @@
+require "digest"
+
+module Mailtruss
+  # ActionMailer / Mail delivery method that sends through the Mailtruss API.
+  #   config.action_mailer.delivery_method = :mailtruss
+  #   config.action_mailer.mailtruss_settings = { api_key: ENV["MAILTRUSS_API_KEY"] }
+  # Envelope recipients not named in To or Cc are sent as Bcc. The Message-ID becomes the idempotency key, so a retried job sends once.
+  class DeliveryMethod
+    attr_accessor :settings
+
+    def initialize(settings = {})
+      @settings = settings
+    end
+
+    def deliver!(mail)
+      client = settings[:client] || Client.new(settings.fetch(:api_key), base_url: settings[:base_url])
+      res = client.emails.send(self.class.payload(mail), idempotency_key: "rails-#{Digest::SHA256.hexdigest(mail.message_id.to_s.empty? ? mail.encoded : mail.message_id)}")
+      mail.header["X-Mailtruss-Id"] = res["id"]
+      res
+    end
+
+    PASS = %w[in-reply-to references list-unsubscribe list-unsubscribe-post list-id].freeze
+
+    # The API request for one message.
+    def self.payload(mail)
+      down = ->(list) { Array(list).map { |a| a.to_s.downcase } }
+      rcpt = down.call(mail.smtp_envelope_to)
+      to = down.call(mail.to).select { |a| rcpt.include?(a) }
+      cc = down.call(mail.cc).select { |a| rcpt.include?(a) }
+      bcc = rcpt - down.call(mail.to) - down.call(mail.cc)
+      to << bcc.shift if to.empty? && cc.empty? && bcc.any?
+      from = mail[:from].formatted.first || mail.smtp_envelope_from
+      p = { from: from, to: to, subject: mail.subject.to_s }
+      p[:cc] = cc if cc.any?
+      p[:bcc] = bcc if bcc.any?
+      p[:reply_to] = Array(mail.reply_to) if mail.reply_to
+      html = mail.html_part ? mail.html_part.decoded : (mail.mime_type == "text/html" ? mail.decoded : nil)
+      text = mail.text_part ? mail.text_part.decoded : (mail.mime_type.nil? || mail.mime_type == "text/plain" ? (mail.multipart? ? nil : mail.decoded) : nil)
+      p[:html] = html if html
+      p[:text] = text if text
+      headers = {}
+      mail.header.fields.each do |f|
+        n = f.name.downcase
+        headers[f.name] = f.value.to_s if PASS.include?(n) || (n.start_with?("x-") && n != "x-mailtruss-tags")
+      end
+      p[:headers] = headers if headers.any?
+      if (tags = mail.header["X-Mailtruss-Tags"])
+        p[:tags] = tags.value.to_s.split(",").map { |pair| k, v = pair.strip.split("=", 2); { name: k, value: v } if k && v }.compact
+      end
+      if mail.attachments.any?
+        p[:attachments] = mail.attachments.map do |a|
+          att = { filename: a.filename, content: Base64.strict_encode64(a.decoded), content_type: a.mime_type }
+          att[:content_id] = a.content_id.to_s.delete("<>") if a.inline?
+          att
+        end
+      end
+      p
+    end
+  end
+end

data/lib/mailtruss/rails.rb

@@ -0,0 +1,12 @@
+require_relative "delivery_method"
+
+module Mailtruss
+  # Registers :mailtruss as an ActionMailer delivery method when Rails is loaded.
+  class Railtie < ::Rails::Railtie
+    initializer "mailtruss.add_delivery_method" do
+      ActiveSupport.on_load(:action_mailer) do
+        ActionMailer::Base.add_delivery_method :mailtruss, Mailtruss::DeliveryMethod, api_key: ENV["MAILTRUSS_API_KEY"]
+      end
+    end
+  end
+end

data/lib/mailtruss/version.rb

@@ -0,0 +1,3 @@
+module Mailtruss
+  VERSION = "0.1.0"
+end

data/lib/mailtruss.rb

@@ -0,0 +1,170 @@
+require "json"
+require "net/http"
+require "openssl"
+require "base64"
+require "uri"
+require_relative "mailtruss/version"
+
+# Ruby client for the Mailtruss email API.
+#
+#   client = Mailtruss::Client.new(ENV.fetch("MAILTRUSS_API_KEY"))
+#   client.emails.send({ from: "hello@yourdomain.com", to: "ana@example.com", subject: "Hi", text: "Hello" }, idempotency_key: "welcome-ana")
+module Mailtruss
+  # Any non-2xx answer. `name` is the stable code (validation_error, rate_limit_exceeded, ...).
+  class Error < StandardError
+    attr_reader :status, :name, :request_id, :retry_after
+    def initialize(status, name, message, request_id = nil, retry_after = nil)
+      super(message)
+      @status, @name, @request_id, @retry_after = status, name, request_id, retry_after
+    end
+  end
+
+  class WebhookError < StandardError; end
+
+  class Client
+    attr_reader :emails, :domains, :api_keys, :contacts, :segments, :topics, :suppressions, :webhooks, :templates, :broadcasts, :logs, :inbound
+
+    # transport: optional callable(method, url, headers, body) -> [status, body, headers] (for tests)
+    def initialize(api_key, base_url: nil, timeout: 30, max_retries: 2, transport: nil)
+      @api_key, @timeout, @max_retries, @transport = api_key, timeout, max_retries, transport
+      @base_url = (base_url || ENV["MAILTRUSS_API_URL"] || "https://mailtruss.com").sub(%r{/+\z}, "")
+      @emails = Emails.new(self)
+      @domains = Domains.new(self)
+      @api_keys = ApiKeys.new(self)
+      @contacts = Resource.new(self, "contacts")
+      @segments = Resource.new(self, "segments")
+      @topics = Resource.new(self, "topics")
+      @suppressions = Suppressions.new(self)
+      @webhooks = Webhooks.new(self)
+      @templates = Templates.new(self)
+      @broadcasts = Broadcasts.new(self)
+      @logs = Resource.new(self, "logs")
+      @inbound = Inbound.new(self)
+    end
+
+    # Any API call. Retries only what is safe to repeat (reads, deletes, writes with an idempotency key) on 429 and 5xx.
+    def request(method, path, body = nil, idempotency_key: nil)
+      headers = { "Authorization" => "Bearer #{@api_key}", "Content-Type" => "application/json", "User-Agent" => "mailtruss-ruby/#{VERSION}" }
+      headers["Idempotency-Key"] = idempotency_key if idempotency_key
+      payload = body.nil? ? nil : JSON.generate(body)
+      retryable = !idempotency_key.nil? || %w[GET DELETE].include?(method)
+      attempt = 0
+      loop do
+        begin
+          status, raw, res_headers = (@transport || method(:http)).call(method, @base_url + path, headers, payload)
+        rescue Net::OpenTimeout, Net::ReadTimeout, SystemCallError, IOError, OpenSSL::SSL::SSLError
+          raise unless retryable && attempt < @max_retries
+          sleep(2**attempt * 0.5); attempt += 1; next
+        end
+        json = raw.to_s.empty? ? {} : (JSON.parse(raw) rescue {})
+        return json if status.between?(200, 299)
+        retry_after = res_headers["retry-after"]&.to_i
+        if retryable && attempt < @max_retries && (status == 429 || status >= 500)
+          sleep(retry_after || 2**attempt); attempt += 1; next
+        end
+        raise Error.new(status, json["name"] || "application_error", json["message"] || "Request failed", res_headers["x-request-id"], retry_after)
+      end
+    end
+
+    private
+
+    def http(method, url, headers, body)
+      uri = URI(url)
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: @timeout, read_timeout: @timeout) do |h|
+        req = Net::HTTPGenericRequest.new(method, !body.nil?, true, uri.request_uri, headers)
+        req.body = body if body
+        res = h.request(req)
+        [res.code.to_i, res.body, res.each_header.to_h]
+      end
+    end
+  end
+
+  # Generic resource: create, list, get, update, remove.
+  class Resource
+    def initialize(client, name)
+      @c, @name = client, name
+    end
+    def create(params, idempotency_key: nil) = @c.request("POST", base, params, idempotency_key: idempotency_key)
+    def list(query = {}) = @c.request("GET", base + q(query))
+    def get(id) = @c.request("GET", "#{base}/#{e(id)}")
+    def update(id, params) = @c.request("PATCH", "#{base}/#{e(id)}", params)
+    def remove(id) = @c.request("DELETE", "#{base}/#{e(id)}")
+
+    private
+
+    def base = "/api/v1/#{@name}"
+    def e(v) = URI.encode_www_form_component(v.to_s).gsub("+", "%20")
+    def q(h)
+      h = h.reject { |_, v| v.nil? || v == "" }
+      h.empty? ? "" : "?#{URI.encode_www_form(h)}"
+    end
+  end
+
+  class Emails < Resource
+    def initialize(c) = super(c, "emails")
+    def send(email, idempotency_key: nil) = @c.request("POST", base, email, idempotency_key: idempotency_key)
+    def batch(emails, idempotency_key: nil) = @c.request("POST", "#{base}/batch", emails, idempotency_key: idempotency_key)
+    def cancel(id) = @c.request("POST", "#{base}/#{e(id)}/cancel")
+    def reschedule(id, scheduled_at) = @c.request("PATCH", "#{base}/#{e(id)}", { scheduled_at: scheduled_at })
+    # The delivery timeline, what each event proves, and a diagnosis when something went wrong.
+    def events(id) = @c.request("GET", "#{base}/#{e(id)}/events")
+  end
+
+  class Domains < Resource
+    def initialize(c) = super(c, "domains")
+    def verify(id) = @c.request("POST", "#{base}/#{e(id)}/verify")
+  end
+
+  class ApiKeys < Resource
+    def initialize(c) = super(c, "api-keys")
+    # Checks this client's own key and what it may do (works with sending-only keys).
+    def verify = @c.request("POST", "#{base}/verify", {})
+  end
+
+  class Suppressions < Resource
+    def initialize(c) = super(c, "suppressions")
+    def add(email) = @c.request("POST", base, { email: email })
+  end
+
+  class Webhooks < Resource
+    def initialize(c) = super(c, "webhooks")
+    def rotate_secret(id) = @c.request("POST", "#{base}/#{e(id)}/rotate-secret")
+  end
+
+  class Templates < Resource
+    def initialize(c) = super(c, "templates")
+    def publish(id, version: nil) = @c.request("POST", "#{base}/#{e(id)}/publish", version ? { version: version } : {})
+  end
+
+  class Broadcasts < Resource
+    def initialize(c) = super(c, "broadcasts")
+    def deliver(id, scheduled_at: nil) = @c.request("POST", "#{base}/#{e(id)}/send", scheduled_at ? { scheduled_at: scheduled_at } : {})
+    def cancel(id) = @c.request("POST", "#{base}/#{e(id)}/cancel")
+  end
+
+  # Mail received at your receiving domains.
+  class Inbound < Resource
+    def initialize(c) = super(c, "inbound")
+    # One attachment; its bytes are base64 in "content".
+    def attachment(id, attachment_id) = @c.request("GET", "#{base}/#{e(id)}/attachments/#{e(attachment_id)}")
+    def raw(id) = @c.request("GET", "#{base}/#{e(id)}/raw")
+  end
+
+  # Verifies a Mailtruss webhook (Standard Webhooks format) and returns the event. Pass the raw body exactly as received.
+  #
+  #   event = Mailtruss.verify_webhook(request.raw_post, request.headers, ENV.fetch("MAILTRUSS_WEBHOOK_SECRET"))
+  def self.verify_webhook(body, headers, secret, tolerance: 300, now: Time.now.to_i)
+    get = ->(*names) { names.each { |n| v = headers[n] || headers[n.split("-").map(&:capitalize).join("-")] || headers["HTTP_#{n.upcase.tr("-", "_")}"]; return v if v }; nil }
+    id, ts, sigs = get.call("webhook-id", "svix-id"), get.call("webhook-timestamp", "svix-timestamp"), get.call("webhook-signature", "svix-signature")
+    raise WebhookError, "Missing webhook-id, webhook-timestamp or webhook-signature header" unless id && ts && sigs
+    raise WebhookError, "Webhook timestamp is outside the allowed window" unless ts.to_s.match?(/\A\d+\z/) && (now - ts.to_i).abs <= tolerance
+    # Secrets issued before 2026-11-14 (whsec_ + 32 url-safe characters) are used as text; newer ones are base64 key bytes.
+    key = secret.match?(/\Awhsec_[A-Za-z0-9_-]{32}\z/) ? secret : Base64.strict_decode64(secret.delete_prefix("whsec_"))
+    expected = Base64.strict_encode64(OpenSSL::HMAC.digest("SHA256", key, "#{id}.#{ts}.#{body}"))
+    ok = sigs.to_s.split.any? { |part| v, sig = part.split(",", 2); v == "v1" && sig && sig.bytesize == expected.bytesize && OpenSSL.fixed_length_secure_compare(sig, expected) }
+    raise WebhookError, "Webhook signature does not match" unless ok
+    JSON.parse(body)
+  end
+end
+
+require_relative "mailtruss/rails" if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,46 @@
+--- !ruby/object:Gem::Specification
+name: mailtruss
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mailtruss
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/mailtruss.rb
+- lib/mailtruss/delivery_method.rb
+- lib/mailtruss/rails.rb
+- lib/mailtruss/version.rb
+homepage: https://mailtruss.com/docs
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://mailtruss.com/docs
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.23
+specification_version: 4
+summary: Ruby client for the Mailtruss email API, with a Rails (ActionMailer) delivery
+  method.
+test_files: []