mailgazelle 1.0.0

data/lib/mailgazelle/error.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module MailGazelle
+  # Base error for SDK failures and API error responses.
+  #
+  # Catch this class when any Mail Gazelle failure should take the same path.
+  # Use a subclass when recovery depends on the cause.
+  class Error < StandardError
+    attr_reader :code, :http_status, :details
+
+    def initialize(message, code:, http_status: 0, details: {})
+      super(message)
+      @code = code
+      @http_status = http_status
+      @details = details
+    end
+  end
+
+  # Raised when the mailer or default client is used without a token.
+  class ApiTokenMissing < Error
+    def initialize(message = "A Mail Gazelle API token is required. Set MAILGAZELLE_API_TOKEN or " \
+                             "config.action_mailer.mailgazelle_settings[:api_token].")
+      super(message, code: "api_token_missing", http_status: 0)
+    end
+  end
+
+  # DNS, TLS, timeout, and other failures before an API response arrives.
+  class TransportError < Error
+    def initialize(message, code: "transport_error", http_status: 0, details: {})
+      super
+    end
+  end
+
+  # An API error that does not map to a more specific class.
+  class ApiError < Error; end
+
+  # 401 unauthenticated, including a token for an archived product.
+  class AuthenticationError < Error; end
+
+  # 403 product_not_ready.
+  class ProductNotReadyError < Error; end
+
+  # 422 validation_error.
+  class ValidationError < Error; end
+
+  # 422 from_not_allowed.
+  class FromNotAllowedError < Error; end
+
+  # 422 recipient_suppressed. The address was stored as rejected and was not sent.
+  class RecipientSuppressedError < Error; end
+
+  # 422 attachment_invalid.
+  class AttachmentError < Error; end
+
+  # 422 attachment_too_large.
+  class AttachmentTooLargeError < Error; end
+
+  # 422 quota_exceeded.
+  class QuotaExceededError < Error; end
+
+  # 422 html_too_large.
+  class HtmlTooLargeError < Error; end
+
+  # 422 message_too_large.
+  class MessageTooLargeError < Error; end
+
+  # 429 rate_limited. The limit is 60 requests per minute per token.
+  class RateLimitError < Error; end
+end

data/lib/mailgazelle/error_mapper.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "json"
+require "mailgazelle/error"
+
+module MailGazelle
+  # Maps a non-success HTTP response onto a typed {Error}.
+  module ErrorMapper
+    CLASSES = {
+      "unauthenticated" => AuthenticationError,
+      "product_not_ready" => ProductNotReadyError,
+      "validation_error" => ValidationError,
+      "from_not_allowed" => FromNotAllowedError,
+      "recipient_suppressed" => RecipientSuppressedError,
+      "attachment_invalid" => AttachmentError,
+      "attachment_too_large" => AttachmentTooLargeError,
+      "quota_exceeded" => QuotaExceededError,
+      "html_too_large" => HtmlTooLargeError,
+      "message_too_large" => MessageTooLargeError,
+      "rate_limited" => RateLimitError
+    }.freeze
+
+    module_function
+
+    def from_response(response)
+      payload = decode(response.body)
+      code = string_or_nil(payload["code"]) || code_from_status(response.status_code)
+      message = string_or_nil(payload["message"]) || "Unexpected Mail Gazelle API error."
+      details = payload["details"].is_a?(Hash) ? payload["details"] : {}
+      error_class = CLASSES.fetch(code, ApiError)
+      error_class.new(message, code: code, http_status: response.status_code, details: details)
+    end
+
+    def decode(body)
+      return {} if body.nil? || body.empty?
+
+      decoded = JSON.parse(body)
+      decoded.is_a?(Hash) ? decoded : {}
+    rescue JSON::ParserError
+      {}
+    end
+
+    def code_from_status(status)
+      case status
+      when 401 then "unauthenticated"
+      when 403 then "product_not_ready"
+      when 422 then "validation_error"
+      when 429 then "rate_limited"
+      else "unknown_error"
+      end
+    end
+
+    def string_or_nil(value)
+      value.is_a?(String) && !value.empty? ? value : nil
+    end
+  end
+end

data/lib/mailgazelle/http/http_client.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "json"
+require "mailgazelle/error"
+require "mailgazelle/error_mapper"
+require "mailgazelle/http/request"
+
+module MailGazelle
+  module Http
+    # Authenticates requests, encodes JSON, and maps API errors to exceptions.
+    class HttpClient
+      def initialize(transport:, base_url:, default_headers:, timeout:, connect_timeout:)
+        @transport = transport
+        @base_url = base_url
+        @default_headers = default_headers
+        @timeout = timeout
+        @connect_timeout = connect_timeout
+      end
+
+      # Send an authenticated JSON request and return the decoded object or list.
+      def request(method, path, json: nil)
+        headers = @default_headers.dup
+        body = nil
+
+        unless json.nil?
+          body = encode(json)
+          headers["Content-Type"] = "application/json"
+        end
+
+        response = @transport.perform(
+          Request.new(
+            http_method: method.to_s.upcase,
+            url: url(path),
+            headers: headers,
+            body: body,
+            timeout: @timeout,
+            connect_timeout: @connect_timeout
+          )
+        )
+
+        raise ErrorMapper.from_response(response) unless response.status_code.between?(200, 299)
+
+        decode_success(response)
+      end
+
+      def url(path)
+        "#{@base_url}/#{path.to_s.sub(%r{\A/}, '')}"
+      end
+
+      private
+
+      def encode(json)
+        JSON.generate(json)
+      rescue JSON::GeneratorError => e
+        raise ApiError.new(
+          "Failed to encode the request body as JSON.",
+          code: "invalid_request",
+          http_status: 0
+        ), cause: e
+      end
+
+      def decode_success(response)
+        return {} if response.body.nil? || response.body.empty?
+
+        decoded = JSON.parse(response.body)
+        unless decoded.is_a?(Hash) || decoded.is_a?(Array)
+          raise ApiError.new(
+            "API returned a non-object JSON payload.",
+            code: "invalid_response",
+            http_status: response.status_code
+          )
+        end
+
+        decoded
+      rescue JSON::ParserError => e
+        raise ApiError.new(
+          "Failed to decode the API response.",
+          code: "invalid_response",
+          http_status: response.status_code
+        ), cause: e
+      end
+    end
+  end
+end

data/lib/mailgazelle/http/net_http_transport.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+require "mailgazelle/error"
+require "mailgazelle/http/request"
+require "mailgazelle/http/response"
+
+module MailGazelle
+  module Http
+    # Default transport backed by +Net::HTTP+. Inject another object with +perform+
+    # when an application wants a different HTTP stack or a test double.
+    class NetHttpTransport
+      METHODS = {
+        "GET" => Net::HTTP::Get,
+        "POST" => Net::HTTP::Post,
+        "PATCH" => Net::HTTP::Patch,
+        "PUT" => Net::HTTP::Put,
+        "DELETE" => Net::HTTP::Delete
+      }.freeze
+
+      def perform(request)
+        uri = URI.parse(request.url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = request.connect_timeout
+        http.read_timeout = request.timeout
+        http.write_timeout = request.timeout if http.respond_to?(:write_timeout=)
+
+        response = http.request(build_request(uri, request))
+        headers = {}
+        response.each_header { |key, value| headers[key.downcase] = value }
+
+        Response.new(status_code: response.code.to_i, body: response.body.to_s, headers: headers)
+      rescue Timeout::Error, IOError, SocketError, SystemCallError, OpenSSL::SSL::SSLError => e
+        message = e.message.to_s
+        message = "The HTTP request failed." if message.empty?
+        raise TransportError.new(message, details: { "error_class" => e.class.name }), cause: e
+      end
+
+      private
+
+      def build_request(uri, request)
+        klass = METHODS[request.http_method.to_s.upcase]
+        raise TransportError, "Unsupported HTTP method #{request.http_method.inspect}." if klass.nil?
+
+        http_request = klass.new(uri.request_uri)
+        request.headers.each { |name, value| http_request[name] = value }
+        http_request.body = request.body unless request.body.nil?
+        http_request
+      end
+    end
+  end
+end

data/lib/mailgazelle/http/request.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module MailGazelle
+  module Http
+    # Outgoing HTTP request passed to a transport.
+    #
+    # A transport is any object that implements +perform+ and returns a {Response}.
+    Request = Data.define(:http_method, :url, :headers, :body, :timeout, :connect_timeout)
+  end
+end

data/lib/mailgazelle/http/response.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module MailGazelle
+  module Http
+    # HTTP response returned by a transport. Header names are lower-case.
+    Response = Data.define(:status_code, :body, :headers)
+  end
+end

data/lib/mailgazelle/mailer.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require "mail"
+require "mailgazelle/attachment"
+require "mailgazelle/client"
+require "mailgazelle/email"
+require "mailgazelle/error"
+
+module MailGazelle
+  # ActionMailer delivery method. Registered as +:mailgazelle+ by {Railtie}.
+  class Mailer
+    SKIPPED_HEADERS = %w[
+      bcc
+      cc
+      content-transfer-encoding
+      content-type
+      date
+      from
+      idempotency-key
+      idempotency_key
+      mailgazelle-idempotency-key
+      mime-version
+      reply-to
+      return-path
+      sender
+      subject
+      tags
+      to
+      x-mailgazelle-message-id
+    ].freeze
+
+    IDEMPOTENCY_HEADERS = %w[
+      idempotency-key
+      idempotency_key
+      mailgazelle-idempotency-key
+    ].freeze
+
+    attr_reader :settings
+
+    def initialize(settings = nil)
+      @config = settings.is_a?(Hash) ? settings : {}
+      @settings = @config.merge(return_response: true)
+    end
+
+    def deliver!(mail)
+      queued = client.emails.send(build_email(mail))
+      remember_id(mail, queued.id)
+      queued
+    end
+
+    private
+
+    def client
+      @client ||= build_client
+    end
+
+    def build_client
+      token = first_present(setting(:api_token), MailGazelle.config.api_token)
+      raise ApiTokenMissing if token.nil? || token.to_s.strip.empty?
+
+      Client.new(
+        api_token: token,
+        base_url: first_present(setting(:api_base), setting(:base_url), MailGazelle.config.api_base),
+        transport: setting(:transport),
+        timeout: first_present(setting(:timeout), MailGazelle.config.timeout) || 30,
+        connect_timeout: first_present(setting(:connect_timeout), MailGazelle.config.connect_timeout) || 10,
+        user_agent_suffix: user_agent_suffix
+      )
+    end
+
+    def user_agent_suffix
+      extra = first_present(setting(:user_agent_suffix), MailGazelle.config.user_agent_suffix)
+      ["rails", extra].compact.map { |value| value.to_s.strip }.reject(&:empty?).join(" ")
+    end
+
+    def setting(key)
+      return @config[key] if @config.key?(key)
+
+      @config[key.to_s] if @config.key?(key.to_s)
+    end
+
+    def first_present(*values)
+      values.find { |value| !value.nil? && !(value.is_a?(String) && value.strip.empty?) }
+    end
+
+    def build_email(message)
+      recipients = address_pairs(message[:to])
+      if recipients.empty?
+        raise ValidationError.new(
+          "A Mail Gazelle message requires at least one To address.",
+          code: "validation_error",
+          http_status: 422
+        )
+      end
+
+      email = Email.to(recipients.first[0], recipients.first[1])
+      recipients.drop(1).each { |address, name| email = email.add_to(address, name) }
+      address_pairs(message[:cc]).each { |address, name| email = email.cc(address, name) }
+      address_pairs(message[:bcc]).each { |address, name| email = email.bcc(address, name) }
+      email = email.subject(message.subject.to_s)
+      email = apply_body(email, message)
+
+      from = address_pairs(message[:from]).first
+      email = email.from(from[0], from[1]) if from
+      address_pairs(message[:reply_to]).each { |address, name| email = email.reply_to(address, name) }
+      email = apply_headers(email, message)
+      apply_attachments(email, message)
+    end
+
+    def apply_body(email, message)
+      if message.multipart?
+        text = part_body(message.text_part)
+        html = part_body(message.html_part)
+        email = email.text(text) if text
+        email = email.html(html) if html
+        return email
+      end
+
+      body = message.body.decoded.to_s
+      return email if body.empty?
+
+      if message.mime_type == "text/html"
+        email.html(body)
+      else
+        email.text(body)
+      end
+    end
+
+    def part_body(part)
+      return nil if part.nil?
+
+      body = part.decoded.to_s
+      body.empty? ? nil : body
+    end
+
+    def apply_headers(email, message)
+      tags = nil
+      idempotency = nil
+      headers = {}
+
+      message.header_fields.each do |field|
+        name = field.name.to_s
+        lowered = name.downcase
+
+        if lowered == "tags"
+          tags = hash_value(field)
+          next
+        end
+
+        if IDEMPOTENCY_HEADERS.include?(lowered)
+          idempotency = field.value.to_s
+          next
+        end
+
+        next if SKIPPED_HEADERS.include?(lowered)
+
+        value = field.value
+        next if value.nil?
+
+        headers[name] = value.to_s
+      end
+
+      headers.each { |name, value| email = email.header(name, value) }
+      tags&.each { |key, value| email = email.tag(key.to_s, value.to_s) }
+      email = email.idempotency_key(idempotency.strip) if idempotency.is_a?(String) && !idempotency.strip.empty?
+      email
+    end
+
+    def hash_value(field)
+      unparsed = field.unparsed_value if field.respond_to?(:unparsed_value)
+      return unparsed if unparsed.is_a?(Hash)
+      return field.value if field.value.is_a?(Hash)
+
+      nil
+    end
+
+    def apply_attachments(email, message)
+      message.attachments.each do |part|
+        filename = part.filename.to_s
+        filename = "attachment" if filename.empty?
+        email = email.attach(
+          Attachment.from_contents(
+            filename,
+            part.body.decoded.to_s,
+            content_type: part.mime_type,
+            content_id: part.inline? ? part.cid : nil
+          )
+        )
+      end
+      email
+    end
+
+    def address_pairs(header)
+      return [] if header.nil? || !header.respond_to?(:addrs)
+
+      header.addrs.filter_map do |address|
+        email = address.address.to_s.strip
+        next if email.empty?
+
+        name = address.display_name.to_s.strip
+        [email, name.empty? ? nil : name]
+      end
+    end
+
+    def remember_id(message, id)
+      return if id.nil? || id.empty?
+
+      message.header["X-MailGazelle-Message-Id"] = id
+      message.message_id = id
+    end
+  end
+end

data/lib/mailgazelle/railtie.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "mailgazelle/mailer"
+
+module MailGazelle
+  # Registers the +:mailgazelle+ ActionMailer delivery method when Rails boots.
+  class Railtie < Rails::Railtie
+    initializer "mailgazelle.action_mailer" do
+      ActiveSupport.on_load(:action_mailer) do
+        add_delivery_method :mailgazelle, MailGazelle::Mailer
+      end
+    end
+  end
+end

data/lib/mailgazelle/version.rb

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

data/lib/mailgazelle.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "mailgazelle/version"
+require "mailgazelle/error"
+require "mailgazelle/configuration"
+require "mailgazelle/address"
+require "mailgazelle/attachment"
+require "mailgazelle/email"
+require "mailgazelle/client"
+
+module MailGazelle
+  class << self
+    def configure
+      yield config
+      @client = nil
+      config
+    end
+
+    def config
+      @config ||= Configuration.new
+    end
+
+    def client
+      @client ||= default_client
+    end
+
+    def reset!
+      @config = Configuration.new
+      @client = nil
+    end
+
+    private
+
+    def default_client
+      token = config.api_token
+      raise ApiTokenMissing if token.nil? || token.to_s.strip.empty?
+
+      Client.new(
+        api_token: token,
+        base_url: config.api_base,
+        timeout: config.timeout || 30,
+        connect_timeout: config.connect_timeout || 10,
+        user_agent_suffix: config.user_agent_suffix
+      )
+    end
+  end
+end
+
+require "mailgazelle/railtie" if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: mailgazelle
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Srdjan Marjanovic
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Send transactional email with the Mail Gazelle API from Ruby, and from
+  Rails via ActionMailer.
+email:
+- srdjan@foobar.rs
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- docs/api.md
+- lib/mailgazelle.rb
+- lib/mailgazelle/address.rb
+- lib/mailgazelle/attachment.rb
+- lib/mailgazelle/client.rb
+- lib/mailgazelle/configuration.rb
+- lib/mailgazelle/domain.rb
+- lib/mailgazelle/domains_resource.rb
+- lib/mailgazelle/email.rb
+- lib/mailgazelle/emails/attachment_meta.rb
+- lib/mailgazelle/emails/email_record.rb
+- lib/mailgazelle/emails/email_status.rb
+- lib/mailgazelle/emails/queued_email.rb
+- lib/mailgazelle/emails_resource.rb
+- lib/mailgazelle/error.rb
+- lib/mailgazelle/error_mapper.rb
+- lib/mailgazelle/http/http_client.rb
+- lib/mailgazelle/http/net_http_transport.rb
+- lib/mailgazelle/http/request.rb
+- lib/mailgazelle/http/response.rb
+- lib/mailgazelle/mailer.rb
+- lib/mailgazelle/railtie.rb
+- lib/mailgazelle/version.rb
+homepage: https://mailgazelle.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://mailgazelle.com
+  source_code_uri: https://github.com/mailgazelle/ruby-sdk
+  changelog_uri: https://github.com/mailgazelle/ruby-sdk/blob/main/CHANGELOG.md
+  allowed_push_host: https://rubygems.org
+  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: 4.0.4
+specification_version: 4
+summary: Ruby and Rails SDK for sending transactional email through Mail Gazelle.
+test_files: []