chain_mail 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5f26cf6af379b9e04d3c78dc39cd1b47a81905b66e4acee3a1cb0b9d13a16517
+  data.tar.gz: d39eb11222bff40e7e6de131dae95ea2c47a6dbfd0001b36b491507ee4808b25
+SHA512:
+  metadata.gz: c5d66fe44f1f6daeedc9c0a5efb7519adb7eb03be921756cd137b63db67584b9d929001fdd7b05ec2e78211c67a01b1187530bff27e9aa1ceaa117f96736b177
+  data.tar.gz: 0b072a3d2ddef79ca2a3427c9162e6f9280bf5b7ad314fc4dd9d6e124d932a51de2ab72d5894dde8f4601f3eda2ade59efa64e3019188248c0e155ceeca0dc27

data/.pre-commit-config.yaml

@@ -0,0 +1,9 @@
+repos:
+  - repo: https://github.com/rubocop/rubocop
+    rev: v1.80.2 # Use the RuboCop version you want
+    hooks:
+      - id: rubocop
+        name: RuboCop
+        entry: rvm 3.3.0 do rubocop
+        language: system
+        types: [ruby]

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,24 @@
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  Exclude:
+    - "db/**/*"
+    - "node_modules/**/*"
+    - "vendor/**/*"
+
+Layout/LineLength:
+  Max: 100
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "chain_mail.gemspec"
+
+Metrics/MethodLength:
+  Max: 35
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/Documentation:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-09-18
+
+- Initial release

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 T
+
+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,220 @@
+![ChainMail Logo](https://raw.githubusercontent.com/taltas/chain_mail/main/assets/images/logo.png)
+
+# ChainMail
+
+[![Coverage Status](https://coveralls.io/repos/github/taltas/chain_mail/badge.svg?branch=main)](https://coveralls.io/github/taltas/chain_mail?branch=main)
+[![Ruby](https://img.shields.io/badge/ruby-3.0+-blue.svg)](https://www.ruby-lang.org)
+[![Build Status](https://github.com/taltas/chain_mail/workflows/Ruby/badge.svg)](https://github.com/taltas/chain_mail/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![RuboCop](https://img.shields.io/badge/rubocop-enabled-brightgreen.svg)](https://github.com/rubocop/rubocop)
+
+ChainMail is a Ruby gem that ensures your transactional **emails never fail** by automatically switching between multiple email providers (SendGrid, Postmark, Mailgun, SES, etc.) when one fails to send. No more lost emails, no more manual intervention required.
+
+## Why ChainMail?
+
+- **Zero Downtime**: If one provider fails, emails automatically route to the next available provider
+- **Easy Setup**: Simple configuration with familiar Rails patterns
+- **Multiple Providers**: Built-in support for all major email services
+- **Error Aggregation**: Get detailed reports on any delivery issues
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'chain_mail'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install chain_mail
+
+## Usage
+
+### Rails Setup
+
+Add a configuration initializer at [`config/initializers/chain_mail.rb`](config/initializers/chain_mail.rb):
+
+```ruby
+ChainMail.configure do |config|
+  config.providers = [
+    { send_grid:  { api_key: ENV["SENDGRID_API_KEY"] } },
+    { mailgun:    { domain: ENV["MAILGUN_DOMAIN"], api_key: ENV["MAILGUN_API_KEY"] } },
+    # Add more providers as needed
+  ]
+end
+```
+
+Set the delivery method in your environment config (e.g. `config/environments/production.rb`):
+
+```ruby
+config.action_mailer.delivery_method = :chain_mail
+```
+
+Send an email using ActionMailer:
+
+```ruby
+class UserMailer < ApplicationMailer
+  def welcome_email(user)
+    mail(
+      to: user.email,
+      from: 'noreply@example.com',
+      subject: 'Welcome!',
+      body: 'Hello and welcome!'
+    )
+  end
+end
+```
+
+## Requirements
+
+- Ruby 3.0 or higher
+- Rails 6.0+ (for Rails integration)
+- Active email provider accounts (SendGrid, Postmark, etc.)
+
+## Architecture
+
+- **Configuration:** Set up providers and credentials in an initializer or before sending.
+- **Delivery:** Handles failover, input validation, and error aggregation.
+- **Providers:** Each adapter implements a standardized interface and error handling.
+
+## Supported Email Providers
+
+ChainMail includes built-in support for the following email providers. Here's how to configure each one in your Rails initializer:
+
+### Amazon SES
+
+```ruby
+ChainMail.configure do |config|
+  config.providers = [
+    { ses: {
+        region: ENV["AWS_REGION"],
+        access_key_id: ENV["AWS_ACCESS_KEY_ID"],
+        secret_access_key: ENV["AWS_SECRET_ACCESS_KEY"]
+      } }
+  ]
+end
+```
+
+### Brevo (formerly Sendinblue)
+
+```ruby
+ChainMail.configure do |config|
+  config.providers = [
+    { brevo: {
+        api_key: ENV["BREVO_API_KEY"],
+        sandbox: ENV["BREVO_SANDBOX"] == "true" # optional
+      } }
+  ]
+end
+```
+
+### Mailgun
+
+```ruby
+ChainMail.configure do |config|
+  config.providers = [
+    { mailgun: {
+        domain: ENV["MAILGUN_DOMAIN"],
+        api_key: ENV["MAILGUN_API_KEY"]
+      } }
+  ]
+end
+```
+
+### OneSignal
+
+```ruby
+ChainMail.configure do |config|
+  config.providers = [
+    { one_signal: { api_key: ENV["ONESIGNAL_API_KEY"] } }
+  ]
+end
+```
+
+### Postmark
+
+```ruby
+ChainMail.configure do |config|
+  config.providers = [
+    { postmark: { api_key: ENV["POSTMARK_API_KEY"] } }
+  ]
+end
+```
+
+### SendGrid
+
+```ruby
+ChainMail.configure do |config|
+  config.providers = [
+    { send_grid: { api_key: ENV["SENDGRID_API_KEY"] } }
+  ]
+end
+```
+
+### SendPulse
+
+```ruby
+ChainMail.configure do |config|
+  config.providers = [
+    { send_pulse: {
+        client_id: ENV["SENDPULSE_CLIENT_ID"],
+        client_secret: ENV["SENDPULSE_CLIENT_SECRET"]
+      } }
+  ]
+end
+```
+
+### Multiple Providers by Priority (send_grid -> mailgun -> ses)
+
+```ruby
+ChainMail.configure do |config|
+  config.providers = [
+    { send_grid: { api_key: ENV["SENDGRID_API_KEY"]} },
+    { mailgun: {
+        domain: ENV["MAILGUN_DOMAIN"],
+        api_key: ENV["MAILGUN_API_KEY"]
+      } },
+    { ses: {
+        region: ENV["AWS_REGION"],
+        access_key_id: ENV["AWS_ACCESS_KEY_ID"],
+        secret_access_key: ENV["AWS_SECRET_ACCESS_KEY"]
+      } }
+  ]
+end
+```
+
+**Note:** Always store API keys and credentials securely using environment variables. Providers are tried in the order listed - the first available provider will handle the email delivery.
+
+## Provider Priorities & Dynamic Configuration
+
+- Providers are tried in the order listed in `config.providers`.
+- You can register/unregister adapters at runtime:
+
+```ruby
+ChainMail.register_provider(:custom, CustomProviderClass)
+ChainMail.unregister_provider(:send_grid)
+```
+
+- You can update provider priorities or credentials dynamically:
+
+```ruby
+ChainMail.config.providers = [
+  { custom: { api_key: "CUSTOM_API_KEY" } },
+  { mailgun: { domain: "MAILGUN_DOMAIN", api_key: "MAILGUN_API_KEY" } }
+]
+```
+
+- API keys and credentials should be stored securely, e.g. using environment variables.
+
+## Development
+
+Check out the repo and start developing!
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/taltas/chain_mail.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/chain_mail.gemspec

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "lib/chain_mail/version"
+
+Gem::Specification.new do |spec|
+  spec.name        = "chain_mail"
+  spec.version     = ChainMail::VERSION
+  spec.authors     = ["Toray Altas"]
+  spec.email       = ["toray.altas@gmail.com"]
+
+  spec.summary     = "Unified transactional email delivery with failover for Ruby/Rails."
+  spec.description =
+    "ChainMail provides a unified interface for sending transactional emails through " \
+    "multiple providers (SendGrid, Postmark, Mailgun, etc.) " \
+    "with automatic failover and Rails integration."
+  spec.homepage    = "https://github.com/taltas/chain_mail"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["homepage_uri"]      = spec.homepage
+  spec.metadata["source_code_uri"]   = "https://github.com/taltas/chain_mail"
+  spec.metadata["changelog_uri"]     = "https://github.com/taltas/chain_mail/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) || f.start_with?(*%w[bin/ test/ spec/ features/ .git .github
+                                                             appveyor Gemfile])
+    end
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Add dependencies here
+  spec.add_dependency "aws-sdk-ses", "~> 1.0"
+  spec.add_dependency "rails", ">= 6.0"
+end

data/config/initializers/chain_mail.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# ChainMail configuration initializer for Rails
+
+# Configure your email providers and credentials here.
+ChainMail.configure do |config|
+  config.providers = [
+    { send_grid: { api_key: ENV.fetch("SENDGRID_API_KEY", nil) } },
+    { mailgun: { domain: ENV.fetch("MAILGUN_DOMAIN", nil),
+                 api_key: ENV.fetch("MAILGUN_API_KEY", nil) } }
+    # Add more providers as needed
+  ]
+end
+
+# Set delivery method in environment config (e.g. config/environments/production.rb):
+# config.action_mailer.delivery_method = :chain_mail

data/lib/chain_mail/configuration.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ChainMail
+  class Configuration
+    attr_accessor :providers
+
+    def initialize
+      @providers = [] # e.g., [:onesignal, :brevo, :sendpulse]
+    end
+  end
+end
+
+# DSL for users
+module ChainMail
+  class << self
+    attr_accessor :config
+
+    def configure
+      self.config ||= Configuration.new
+      yield(config)
+    end
+  end
+end

data/lib/chain_mail/delivery.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module ChainMail
+  class Delivery
+    def initialize(values = {})
+      # values can include any ActionMailer options like :to, :from, :subject
+      @settings = values
+    end
+
+    # Called by Rails ActionMailer
+    def deliver!(mail)
+      validate_mail!(mail)
+      results = try_providers(mail)
+      return unless results.none? { |r| r[:success] }
+
+      handle_delivery_errors(mail, results)
+    end
+
+    private
+
+    def validate_mail!(mail)
+      required_fields = %i[to from subject body]
+      missing = required_fields.select do |field|
+        !mail.respond_to?(field) ||
+          (value = mail.send(field)).nil? ||
+          (value.respond_to?(:empty?) && value.empty?)
+      end
+      return if missing.empty?
+
+      raise "Mail object missing or blank: #{missing.join(', ')}"
+    end
+
+    def try_providers(mail)
+      providers = ChainMail.config.providers
+      validate_providers!(providers)
+
+      results = []
+      providers.each do |provider|
+        results.concat(try_single_provider(mail, provider))
+        return results if successful?(results)
+      end
+      results
+    end
+
+    def validate_providers!(providers)
+      raise "ChainMail: No providers configured" if providers.nil? || providers.empty?
+      return if providers.all? { |p| p.is_a?(Hash) && p.size == 1 }
+
+      raise "ChainMail: Provider config must be a hash with one key-value pair"
+    end
+
+    def successful?(results)
+      results.any? { |r| r[:success] }
+    end
+
+    def try_single_provider(mail, provider)
+      name, creds = provider.first
+      return invalid_credentials_result(name) unless creds.is_a?(Hash)
+
+      begin
+        result = provider_class(name).deliver(mail, creds)
+        return success_result(name, result) if result[:success]
+
+        error_result(name, result)
+      rescue StandardError => e
+        exception_result(name, e)
+      end
+    end
+
+    def invalid_credentials_result(name)
+      [{ provider: name, error: "Credentials must be a hash", response: nil }]
+    end
+
+    def success_result(name, result)
+      Rails.logger.info("[ChainMail] Email sent via #{name}")
+      [{ provider: name, success: true, error: nil, response: result[:response] }]
+    end
+
+    def error_result(name, result)
+      Rails.logger.error("[ChainMail] Provider #{name} failed: #{result[:error]}")
+      [{ provider: name, error: result[:error], response: result[:response] }]
+    end
+
+    def exception_result(name, exception)
+      Rails.logger.error("[ChainMail] Provider #{name} raised: #{exception.message}")
+      [{ provider: name, error: exception.message, response: nil }]
+    end
+
+    def handle_delivery_errors(mail, errors)
+      return if errors.empty?
+
+      error_messages = errors.map { |err| "#{err[:provider]}: #{err[:error]}" }.join("; ")
+      raise(
+        "ChainMail: All email providers failed for #{mail.to.join(', ')}. " \
+        "Errors: #{error_messages}"
+      )
+    end
+
+    # Provider class resolution using ChainMail.provider_registry
+    def provider_class(name)
+      klass = ChainMail.provider_registry[name.to_sym]
+      raise "ChainMail: Unknown provider #{name}" unless klass
+
+      klass
+    end
+  end
+end

data/lib/chain_mail/providers/base.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module ChainMail
+  module Providers
+    class Base
+      def self.deliver(mail, creds)
+        raise NotImplementedError, "Subclasses must implement deliver(mail, creds)"
+      end
+
+      # Helper for HTTP requests, error parsing, etc.
+      def self.post_json(url, headers, payload)
+        uri = URI(url)
+        req = Net::HTTP::Post.new(uri, headers)
+        req.body = payload.to_json
+        begin
+          res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
+          if res.is_a?(Net::HTTPSuccess)
+            { success: true, response: res, error: nil }
+          else
+            { success: false, response: res, error: "API error: #{res.code} #{res.body}" }
+          end
+        rescue StandardError => e
+          { success: false, response: nil, error: e.message }
+        end
+      end
+    end
+  end
+end

data/lib/chain_mail/providers/brevo.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ChainMail
+  module Providers
+    class Brevo < Base
+      def self.deliver(mail, creds)
+        payload = {
+          sender: { email: mail.from.first },
+          to: mail.to.map { |t| { email: t } },
+          subject: mail.subject,
+          htmlContent: mail.body.decoded
+        }
+        headers = {
+          "api-key" => creds[:api_key],
+          "Content-Type" => "application/json"
+        }
+
+        headers.merge!("X-Sib-Sandbox" => "drop") if creds[:sandbox]
+        post_json("https://api.brevo.com/v3/smtp/email", headers, payload)
+      end
+    end
+  end
+end

data/lib/chain_mail/providers/mailgun.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module ChainMail
+  module Providers
+    class Mailgun < Base
+      def self.deliver(mail, creds)
+        domain = creds[:domain]
+        api_key = creds[:api_key]
+
+        return error_result("MAILGUN_DOMAIN or MAILGUN_API_KEY not set") unless domain && api_key
+
+        send_mailgun_request(mail, domain, api_key)
+      end
+
+      def self.send_mailgun_request(mail, domain, api_key)
+        req = build_mailgun_request(mail, domain, api_key)
+        perform_mailgun_request(req)
+      end
+
+      def self.build_mailgun_request(mail, domain, api_key)
+        uri = URI("https://api.mailgun.net/v3/#{domain}/messages")
+        req = Net::HTTP::Post.new(uri)
+        req.basic_auth("api", api_key)
+        req.set_form_data(
+          from: mail.from.first,
+          to: mail.to.join(","),
+          subject: mail.subject,
+          html: mail.body.decoded
+        )
+        req
+      end
+
+      def self.perform_mailgun_request(req)
+        res = Net::HTTP.start(req.uri.hostname, req.uri.port, use_ssl: true) { |http| http.request(req) }
+        return success_result(res) if res.is_a?(Net::HTTPSuccess)
+
+        error_result("Mailgun API error: #{res.code} #{res.body}", res)
+      rescue StandardError => e
+        error_result(e.message)
+      end
+
+      def self.success_result(response)
+        { success: true, response: response, error: nil }
+      end
+
+      def self.error_result(error, response = nil)
+        { success: false, response: response, error: error }
+      end
+    end
+  end
+end

data/lib/chain_mail/providers/one_signal.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module ChainMail
+  module Providers
+    class OneSignal < Base
+      def self.deliver(mail, creds)
+        payload = {
+          include_email_tokens: mail.to,
+          subject: mail.subject,
+          body: mail.body.decoded,
+          from_email: mail.from.first
+        }
+        headers = {
+          "Authorization" => "Basic #{creds[:api_key]}",
+          "Content-Type" => "application/json"
+        }
+        post_json("https://onesignal.com/api/v1/notifications", headers, payload)
+      end
+    end
+  end
+end

data/lib/chain_mail/providers/postmark.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module ChainMail
+  module Providers
+    class Postmark < Base
+      def self.deliver(mail, creds)
+        payload = {
+          From: mail.from.first,
+          To: mail.to.join(","),
+          Subject: mail.subject,
+          HtmlBody: mail.body.decoded
+        }
+        headers = {
+          "X-Postmark-Server-Token" => creds[:api_key],
+          "Content-Type" => "application/json"
+        }
+        post_json("https://api.postmarkapp.com/email", headers, payload)
+      end
+    end
+  end
+end

data/lib/chain_mail/providers/send_grid.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+
+module ChainMail
+  module Providers
+    class SendGrid < Base
+      def self.deliver(mail, creds)
+        if creds[:api_key].nil? || creds[:api_key].to_s.strip.empty?
+          raise KeyError,
+                "Missing SendGrid API key"
+        end
+
+        payload = {
+          personalizations: [{ to: mail.to.map { |t| { email: t } } }],
+          from: { email: mail.from.first },
+          subject: mail.subject,
+          content: [{ type: "text/html", value: mail.body.decoded }]
+        }
+        headers = {
+          "Authorization" => "Bearer #{creds[:api_key]}",
+          "Content-Type" => "application/json"
+        }
+        post_json("https://api.sendgrid.com/v3/mail/send", headers, payload)
+      end
+    end
+  end
+end