mailsenpai 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a285a6487d8b02c8e68e983f3e3013c0f6c1ff46b0cee02eae637e5fd1004db9
+  data.tar.gz: 109b14fafb936421447187a32634b05569497828c0d396d39f1d3790f6be3acd
+SHA512:
+  metadata.gz: a5db8b0577bf3eb633f120f70cbe6c22625fe1385bca886ee8da3382c28e9ba60417ea5daccbb6fe8da9103fb3d2aadc90678a28d6fb2eadadfd9c5e05608cc6
+  data.tar.gz: 9e878499379eda00086458964d5c7a984227599ba144e89e4272b6e9a69914ef88f182f7c029d84357b4b84be29bcea547d9a0c6c42e39c0e9c8f506182ac89f

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.0.0
+
+- Initial release: API client, webhook signature verification, ActionMailer delivery method `:mailsenpai`.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MailSenpai
+
+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,108 @@
+# mailsenpai (Ruby)
+
+Ruby client and ActionMailer delivery method for **SMTP Senpai by MailSenpai**, the EU-hosted SMTP relay and
+transactional email API. Standard library only (`net/http`, `json`, `openssl`) plus `base64`.
+
+Docs: https://en.mailsenpai.com/smtp-api/ · Product: https://en.mailsenpai.com/smtp-senpai/ · All integrations: https://en.mailsenpai.com/integrations/
+Source code and issues: https://gitlab.com/smtp-senpai/mailsenpai-ruby
+
+## Install
+
+```ruby
+# Gemfile
+gem "mailsenpai"
+```
+
+Ruby 3.1+. Get your API key (it starts with `msp_`) in the MailSenpai customer area, SMTP Senpai page.
+
+## Rails / ActionMailer
+
+```ruby
+# config/environments/production.rb
+config.action_mailer.delivery_method = :mailsenpai
+config.action_mailer.mailsenpai_settings = {
+  api_key: Rails.application.credentials.dig(:mailsenpai, :api_key) # default: ENV["MAILSENPAI_API_KEY"]
+}
+```
+
+The delivery method is registered for you in Rails. Without Rails, `require "action_mailer"` before
+`require "mailsenpai"`, or call `MailSenpai.add_delivery_method` once.
+
+Then use your mailers as usual. Supported: text and HTML parts, attachments, Reply-To, display name in `from`,
+custom `X-...` headers (other headers are dropped by the API). After delivery, `message.message_id` is the
+Message-ID given by SMTP Senpai. Add an `Idempotency-Key` header (`headers["Idempotency-Key"] = "order-#{order.id}"`)
+so that a retried job never sends the same email twice within 24 hours.
+
+Good to know:
+
+- every recipient (To, Cc and Bcc) gets an individual copy, so Cc addresses are not visible to the other
+  recipients; use SMTP (`relay.mailsenpai.com`, port 2525, STARTTLS) if you need a visible Cc;
+- messages with more than 50 recipients are split into several API calls; up to 10 attachments, 10 MB in total;
+- recipients on your suppression list are skipped without error; API errors raise `MailSenpai::Error` subclasses
+  (respecting `raise_delivery_errors`).
+
+## API client
+
+```ruby
+require "mailsenpai"
+
+client = MailSenpai::Client.new("msp_...")   # or ENV["MAILSENPAI_API_KEY"]
+
+result = client.send_email(
+  to: "customer@example.com",                # or an array of up to 50 addresses
+  from: "orders@yourdomain.com",             # on a verified domain
+  from_name: "Your shop",
+  subject: "Order 10293 confirmed",
+  html: "<p>Thanks, your order is confirmed.</p>",
+  reply_to: "support@yourdomain.com",
+  headers: { "X-Order" => "10293" },
+  attachments: [{ filename: "invoice.pdf", content: File.binread("invoice.pdf"), content_type: "application/pdf" }],
+  idempotency_key: "order-10293"
+)
+result.sent?          # => true
+result.message_id     # => "9f2c...@yourdomain.com"
+result.not_sent       # => recipients on the suppression list, with #reason
+
+client.status                                  # SMTP details, monthly volume, tracking
+client.events(limit: 50, type: "bounce")       # latest events
+client.each_event(after: last_id) { |e| ... }  # everything new since last_id, oldest first
+client.suppressions(search: "example.com")
+client.suppress("someone@example.com", note: "asked to stop")
+client.unsuppress("someone@example.com")
+```
+
+Errors: `AuthenticationError` (401), `PermissionDeniedError` (403), `NotFoundError` (404), `ConflictError` (409),
+`PayloadTooLargeError` (413), `UnprocessableEntityError` (422), `RateLimitError` (429), `UpstreamError` (502),
+`ConnectionError`. Each has `#status` and `#body`; the message is the API text (in Italian).
+
+## Webhooks
+
+```ruby
+class MailsenpaiWebhooksController < ActionController::API
+  def create
+    event = MailSenpai::Webhook.construct_event(
+      request.raw_post,
+      request.headers["X-MailSenpai-Signature"],
+      ENV.fetch("MAILSENPAI_WEBHOOK_SECRET")       # whsec_...
+    )
+    # event["type"], event["data"]["email"], event["data"]["message_id"] ...
+    head :no_content
+  rescue MailSenpai::WebhookVerificationError
+    head :bad_request
+  end
+end
+```
+
+Signature: `t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<body>")>`, 5 minutes tolerance by default.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+gem build mailsenpai.gemspec
+```
+
+## License
+
+MIT, © MailSenpai.

data/lib/mailsenpai/client.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "net/http"
+require "uri"
+
+module MailSenpai
+  # Outcome for one recipient.
+  RecipientResult = Struct.new(:email, :sent, :message_id, :reason, :error, keyword_init: true) do
+    alias_method :sent?, :sent
+  end
+
+  # Normalised response of POST /invio, for one or many recipients.
+  class SendResult
+    attr_reader :results, :remaining, :raw
+
+    def initialize(results:, remaining: nil, over_plan: false, replayed: false, raw: {})
+      @results = results
+      @remaining = remaining
+      @over_plan = over_plan
+      @replayed = replayed
+      @raw = raw
+    end
+
+    def over_plan? = @over_plan
+    def replayed? = @replayed
+    def sent? = results.any?(&:sent)
+    def sent_count = results.count(&:sent)
+    def not_sent = results.reject(&:sent)
+    def message_ids = results.select(&:sent).map(&:message_id).compact
+    def message_id = message_ids.first
+  end
+
+  # Synchronous client for the SMTP Senpai REST API.
+  #
+  #   client = MailSenpai::Client.new("msp_...")   # or ENV["MAILSENPAI_API_KEY"]
+  #   client.send_email(to: "customer@example.com", from: "orders@yourdomain.com",
+  #                     subject: "Order confirmed", html: "<p>Thanks!</p>")
+  class Client
+    DEFAULT_BASE_URL = "https://app.mailsenpai.com/relay/v1"
+    MAX_RECIPIENTS = 50
+    MAX_ATTACHMENTS = 10
+    EVENT_TYPES = %w[sent delivered bounce defer complaint open click dropped].freeze
+
+    attr_reader :base_url, :timeout
+
+    def initialize(api_key = nil, base_url: nil, timeout: 30)
+      @api_key = api_key || ENV.fetch("MAILSENPAI_API_KEY", nil)
+      raise Error, "Missing API key: pass api_key or set MAILSENPAI_API_KEY." if @api_key.to_s.empty?
+
+      @base_url = (base_url || ENV["MAILSENPAI_BASE_URL"] || DEFAULT_BASE_URL).chomp("/")
+      @timeout = timeout
+    end
+
+    def inspect = "#<MailSenpai::Client base_url=#{@base_url.inspect}>"
+
+    # Sends an email. +to+ is an address or an array of up to 50 (each gets an individual copy).
+    # +attachments+: [{filename:, content: (raw bytes), content_type:}]. +headers+: only X-... are kept.
+    def send_email(to:, from:, subject:, text: nil, html: nil, from_name: nil, reply_to: nil,
+                   headers: nil, attachments: nil, idempotency_key: nil)
+      raise ArgumentError, "Provide text, html or both." if text.nil? && html.nil?
+
+      recipients = normalize_recipients(to)
+      payload = { "to" => recipients, "from" => from, "subject" => subject.to_s }
+      payload["text"] = text unless text.nil?
+      payload["html"] = html unless html.nil?
+      payload["from_name"] = from_name if from_name && !from_name.empty?
+      payload["reply_to"] = reply_to if reply_to && !reply_to.empty?
+      payload["headers"] = headers.to_h.transform_keys(&:to_s).transform_values(&:to_s) if headers && !headers.empty?
+      if attachments && !attachments.empty?
+        raise ArgumentError, "Up to #{MAX_ATTACHMENTS} attachments per email." if attachments.size > MAX_ATTACHMENTS
+
+        payload["attachments"] = attachments.map { |a| attachment_to_api(a) }
+      end
+      extra = idempotency_key ? { "Idempotency-Key" => idempotency_key.to_s } : {}
+      body, response_headers = request(:post, "/invio", body: payload, headers: extra)
+      build_send_result(body, recipients, response_headers)
+    end
+
+    def status = request(:get, "/stato").first
+    def stats(days: nil) = request(:get, "/statistiche", params: { giorni: days }).first
+
+    # One page of events. Without +after+: the latest, newest first. With +after+: oldest first.
+    # Returns {"eventi" => [...], "prossimo" => "...", "altri" => true/false}.
+    def events(after: nil, limit: nil, type: nil)
+      raise ArgumentError, "Unknown event type #{type.inspect}" if type && !EVENT_TYPES.include?(type.to_s)
+
+      request(:get, "/eventi", params: { dopo: after, quanti: limit, tipo: type }).first
+    end
+
+    # Yields every event after the cursor (oldest first), following "prossimo" while "altri" is true.
+    def each_event(after: 0, type: nil, page_size: 500)
+      return enum_for(:each_event, after: after, type: type, page_size: page_size) unless block_given?
+
+      cursor = after.to_i
+      loop do
+        page = events(after: cursor, limit: page_size, type: type)
+        list = page["eventi"] || []
+        list.each { |event| yield event }
+        next_cursor = page["prossimo"] ? page["prossimo"].to_i : list.last&.fetch("event_id", nil)&.to_i
+        break if !page["altri"] || list.empty? || next_cursor.nil? || next_cursor <= cursor
+
+        cursor = next_cursor
+      end
+    end
+
+    def suppressions(limit: nil, search: nil) = request(:get, "/soppressi", params: { quanti: limit, cerca: search }).first
+
+    def suppress(email, note: nil)
+      payload = { "email" => email }
+      payload["nota"] = note if note
+      request(:post, "/sopprimi", body: payload).first
+    end
+
+    def unsuppress(email) = request(:post, "/riammetti", body: { "email" => email }).first
+
+    def webhook = request(:get, "/webhook").first["webhook"] || {}
+
+    def set_webhook(url:, events: nil, active: true, rotate_secret: false)
+      payload = { "url" => url, "attivo" => active }
+      payload["eventi"] = events if events
+      payload["nuovo_segreto"] = true if rotate_secret
+      request(:post, "/webhook", body: payload).first["webhook"] || {}
+    end
+
+    def test_webhook = request(:post, "/webhook/prova").first
+
+    # Low-level call: returns [parsed JSON body, response headers (lowercase keys)].
+    def request(method, path, params: nil, body: nil, headers: {})
+      uri = URI.parse(@base_url + path)
+      query = (params || {}).compact
+      uri.query = URI.encode_www_form(query) unless query.empty?
+
+      klass = method == :post ? Net::HTTP::Post : Net::HTTP::Get
+      req = klass.new(uri)
+      req["Authorization"] = "Bearer #{@api_key}"
+      req["Accept"] = "application/json"
+      req["User-Agent"] = "mailsenpai-ruby/#{VERSION}"
+      headers.each { |k, v| req[k] = v }
+      if body
+        req["Content-Type"] = "application/json; charset=utf-8"
+        req.body = JSON.generate(body)
+      end
+
+      response = begin
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                            open_timeout: @timeout, read_timeout: @timeout) { |http| http.request(req) }
+      rescue SocketError, SystemCallError, Timeout::Error, OpenSSL::SSL::SSLError, IOError => e
+        raise ConnectionError, "Could not reach SMTP Senpai: #{e.message}"
+      end
+
+      status = response.code.to_i
+      parsed = begin
+        response.body.to_s.empty? ? {} : JSON.parse(response.body)
+      rescue JSON::ParserError
+        raise APIError.new("Unexpected non-JSON response from SMTP Senpai (HTTP #{status}).", status: status)
+      end
+      parsed = { "data" => parsed } unless parsed.is_a?(Hash)
+
+      if status >= 400 || parsed["ok"] == false
+        message = parsed["errore"] || parsed["error"] || "HTTP #{status}"
+        raise STATUS_ERRORS.fetch(status, APIError).new(message, status: status, body: parsed)
+      end
+
+      [parsed, response.each_header.to_h]
+    end
+
+    private
+
+    def normalize_recipients(to)
+      if to.is_a?(Array)
+        list = to.map { |a| a.to_s.strip }.reject(&:empty?)
+        raise ArgumentError, "A recipient is required." if list.empty?
+        raise ArgumentError, "Up to #{MAX_RECIPIENTS} recipients per call (got #{list.size})." if list.size > MAX_RECIPIENTS
+
+        list
+      else
+        addr = to.to_s.strip
+        raise ArgumentError, "A recipient is required." if addr.empty?
+
+        addr
+      end
+    end
+
+    def attachment_to_api(att)
+      att = att.transform_keys(&:to_s)
+      filename = att["filename"] || att["nome"]
+      content = att["content"] || att["contenuto"]
+      raise ArgumentError, "Each attachment needs filename and content." if filename.nil? || content.nil?
+
+      out = { "filename" => filename, "content" => att["base64"] ? content : Base64.strict_encode64(content) }
+      type = att["content_type"] || att["tipo"]
+      out["content_type"] = type if type
+      out
+    end
+
+    def build_send_result(body, recipients, response_headers)
+      results =
+        if body["risultati"].is_a?(Array)
+          body["risultati"].map do |row|
+            RecipientResult.new(email: row["a"], sent: row["inviato"] ? true : false, message_id: row["id_messaggio"],
+                                reason: row["motivo"], error: row["errore"])
+          end
+        else
+          email = recipients.is_a?(Array) ? recipients.first : recipients
+          [RecipientResult.new(email: email, sent: body["inviato"] ? true : false,
+                               message_id: body["id_messaggio"], reason: body["motivo"])]
+        end
+      SendResult.new(results: results, remaining: body["residuo"]&.to_i, over_plan: body["oltre_il_piano"] ? true : false,
+                     replayed: response_headers["idempotent-replayed"].to_s.downcase == "true", raw: body)
+    end
+  end
+end

data/lib/mailsenpai/delivery_method.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module MailSenpai
+  # Delivery method for the mail gem / ActionMailer.
+  #
+  #   config.action_mailer.delivery_method = :mailsenpai
+  #   config.action_mailer.mailsenpai_settings = { api_key: ENV["MAILSENPAI_API_KEY"] }
+  #
+  # Every recipient (To, Cc and Bcc) gets an individual copy: Cc addresses are not shown to the
+  # other recipients. Messages with more than 50 recipients are split into several API calls.
+  class DeliveryMethod
+    SKIPPED_HEADERS = %w[from to cc bcc subject reply-to sender return-path content-type
+                         content-transfer-encoding mime-version date message-id idempotency-key].freeze
+
+    attr_accessor :settings
+
+    def initialize(settings = {})
+      @settings = settings.to_h.transform_keys(&:to_sym)
+    end
+
+    def deliver!(mail)
+      recipients = Array(mail.smtp_envelope_to).map(&:to_s).uniq(&:downcase)
+      raise ArgumentError, "SMTP Senpai: the email has no recipients." if recipients.empty?
+
+      payload = build_payload(mail)
+      results = recipients.each_slice(Client::MAX_RECIPIENTS).map do |chunk|
+        client.send_email(to: chunk, **payload)
+      end
+
+      first_id = results.flat_map(&:message_ids).first
+      mail.message_id = first_id if first_id
+      if results.none?(&:sent?) && results.flat_map(&:results).any?(&:error)
+        errors = results.flat_map(&:not_sent).map { |r| "#{r.email}: #{r.error || r.reason}" }
+        raise UpstreamError.new("SMTP Senpai did not send the email: #{errors.join('; ')}", status: 200)
+      end
+
+      settings[:return_response] ? results : self
+    end
+
+    def client
+      @client ||= Client.new(settings[:api_key], base_url: settings[:base_url], timeout: settings[:timeout] || 30)
+    end
+
+    def build_payload(mail)
+      from = mail[:from]&.addrs&.first
+      raise ArgumentError, "SMTP Senpai: the email has no From address." unless from
+
+      envelope_from = mail.smtp_envelope_from.to_s
+      payload = {
+        from: envelope_from.empty? ? from.address : envelope_from,
+        from_name: from.display_name,
+        subject: mail.subject.to_s,
+        reply_to: mail[:reply_to]&.addrs&.first&.address,
+        idempotency_key: mail.header["Idempotency-Key"]&.value
+      }
+
+      text, html = bodies(mail)
+      payload[:text] = text if text
+      payload[:html] = html if html
+      payload[:text] = "" if text.nil? && html.nil?
+
+      headers = custom_headers(mail)
+      payload[:headers] = headers unless headers.empty?
+
+      unless mail.attachments.empty?
+        payload[:attachments] = mail.attachments.map do |part|
+          { filename: part.filename, content: part.decoded, content_type: part.mime_type }
+        end
+      end
+      payload.compact
+    end
+
+    private
+
+    def bodies(mail)
+      text = mail.text_part&.decoded
+      html = mail.html_part&.decoded
+      if !mail.multipart?
+        body = mail.body.decoded
+        mail.mime_type == "text/html" ? html = body : text = body
+      end
+      [text, html]
+    end
+
+    def custom_headers(mail)
+      mail.header.fields.each_with_object({}) do |field, out|
+        name = field.name.to_s
+        next if SKIPPED_HEADERS.include?(name.downcase)
+        next unless name.downcase.start_with?("x-")
+
+        out[name] = field.value.to_s
+      end
+    end
+  end
+end

data/lib/mailsenpai/errors.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module MailSenpai
+  # Base class for every error of this gem. +message+ is the API text (in Italian) or a local description.
+  class Error < StandardError
+    attr_reader :status, :body
+
+    def initialize(message = nil, status: nil, body: nil)
+      super(message)
+      @status = status
+      @body = body || {}
+    end
+  end
+
+  class ConnectionError < Error; end
+  class APIError < Error; end
+  class BadRequestError < APIError; end            # 400
+  class AuthenticationError < APIError; end        # 401
+  class PermissionDeniedError < APIError; end      # 403 unverified domain, suspended, being activated
+  class NotFoundError < APIError; end              # 404
+  class ConflictError < APIError; end              # 409
+  class PayloadTooLargeError < APIError; end       # 413
+  class UnprocessableEntityError < APIError; end   # 422
+  class RateLimitError < APIError; end             # 429 monthly volume used up / spending cap
+  class UpstreamError < APIError; end              # 502 sending server refused the message
+  class WebhookVerificationError < Error; end
+
+  STATUS_ERRORS = {
+    400 => BadRequestError, 401 => AuthenticationError, 403 => PermissionDeniedError,
+    404 => NotFoundError, 409 => ConflictError, 413 => PayloadTooLargeError,
+    422 => UnprocessableEntityError, 429 => RateLimitError, 502 => UpstreamError
+  }.freeze
+end

data/lib/mailsenpai/railtie.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module MailSenpai
+  # Registers the :mailsenpai delivery method in Rails apps.
+  class Railtie < ::Rails::Railtie
+    initializer "mailsenpai.add_delivery_method", before: "action_mailer.set_configs" do
+      ActiveSupport.on_load(:action_mailer) { MailSenpai.add_delivery_method(self) }
+    end
+  end
+end

data/lib/mailsenpai/version.rb

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

data/lib/mailsenpai/webhook.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module MailSenpai
+  # Verification of X-MailSenpai-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>.
+  module Webhook
+    HEADER = "X-MailSenpai-Signature"
+    DEFAULT_TOLERANCE = 300
+
+    module_function
+
+    def sign(payload, secret, timestamp: Time.now.to_i)
+      "t=#{timestamp.to_i},v1=#{compute(payload, secret, timestamp.to_i)}"
+    end
+
+    def compute(payload, secret, timestamp)
+      OpenSSL::HMAC.hexdigest("SHA256", secret.to_s, "#{timestamp}.#{payload}")
+    end
+
+    # Raises WebhookVerificationError unless the signature is valid; returns true otherwise.
+    def verify!(payload, header, secret, tolerance: DEFAULT_TOLERANCE, now: Time.now.to_i)
+      raise WebhookVerificationError, "A non-empty webhook secret is required." if secret.to_s.empty?
+      raise WebhookVerificationError, "Missing #{HEADER} header." if header.to_s.empty?
+
+      timestamp = nil
+      signatures = []
+      header.to_s.split(",").each do |part|
+        key, value = part.strip.split("=", 2)
+        if key == "t" && value.to_s.match?(/\A\d+\z/)
+          timestamp = value.to_i
+        elsif key == "v1" && !value.to_s.empty?
+          signatures << value.downcase
+        end
+      end
+      raise WebhookVerificationError, "Malformed signature header." if timestamp.nil? || signatures.empty?
+      if tolerance && (now.to_i - timestamp).abs > tolerance
+        raise WebhookVerificationError, "Timestamp outside the tolerance window."
+      end
+
+      expected = compute(payload, secret, timestamp)
+      return true if signatures.any? { |sig| secure_compare(expected, sig) }
+
+      raise WebhookVerificationError, "Signature does not match."
+    end
+
+    def valid?(payload, header, secret, **opts)
+      verify!(payload, header, secret, **opts)
+    rescue WebhookVerificationError
+      false
+    end
+
+    # Verifies and returns the parsed event: {"id", "type", "created_at", "data" => {...}, "account", "test"}.
+    def construct_event(payload, header, secret, **opts)
+      verify!(payload, header, secret, **opts)
+      event = JSON.parse(payload)
+      raise WebhookVerificationError, "The webhook body is not a JSON object." unless event.is_a?(Hash)
+
+      event
+    rescue JSON::ParserError
+      raise WebhookVerificationError, "The webhook body is not valid JSON."
+    end
+
+    def secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      OpenSSL.fixed_length_secure_compare(a, b)
+    end
+  end
+end

data/lib/mailsenpai.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "mailsenpai/version"
+require_relative "mailsenpai/errors"
+require_relative "mailsenpai/client"
+require_relative "mailsenpai/webhook"
+require_relative "mailsenpai/delivery_method"
+
+# SMTP Senpai by MailSenpai: EU SMTP relay and transactional email API.
+module MailSenpai
+  # Registers :mailsenpai on an ActionMailer::Base-like class (done for you in Rails).
+  def self.add_delivery_method(base = ::ActionMailer::Base)
+    return if base.delivery_methods.key?(:mailsenpai)
+
+    base.add_delivery_method :mailsenpai, MailSenpai::DeliveryMethod, api_key: ENV.fetch("MAILSENPAI_API_KEY", nil)
+  end
+end
+
+if defined?(::Rails::Railtie)
+  require_relative "mailsenpai/railtie"
+elsif defined?(::ActionMailer::Base)
+  MailSenpai.add_delivery_method
+end

metadata

@@ -0,0 +1,142 @@
+--- !ruby/object:Gem::Specification
+name: mailsenpai
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- MailSenpai
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: actionmailer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: mail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.20'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.20'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: 'Send transactional email through SMTP Senpai by MailSenpai, the EU-hosted
+  SMTP relay and email API: API client (send, events, suppression list), webhook signature
+  verification and an ActionMailer delivery method (:mailsenpai).'
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/mailsenpai.rb
+- lib/mailsenpai/client.rb
+- lib/mailsenpai/delivery_method.rb
+- lib/mailsenpai/errors.rb
+- lib/mailsenpai/railtie.rb
+- lib/mailsenpai/version.rb
+- lib/mailsenpai/webhook.rb
+homepage: https://en.mailsenpai.com/integrations/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://en.mailsenpai.com/integrations/
+  documentation_uri: https://en.mailsenpai.com/smtp-api/
+  source_code_uri: https://gitlab.com/smtp-senpai/mailsenpai-ruby
+  bug_tracker_uri: https://gitlab.com/smtp-senpai/mailsenpai-ruby/-/issues
+  changelog_uri: https://gitlab.com/smtp-senpai/mailsenpai-ruby/-/blob/main/CHANGELOG.md
+  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: Ruby client and ActionMailer delivery method for SMTP Senpai by MailSenpai
+test_files: []