duva-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f1d0a7b608bf775dd3ec350b28df315969e99419004c724f389d29c3d4033a84
+  data.tar.gz: 30977e85fbe65ab750a0ca22d5cc5eacec48222c68e9091735fb7c6aeaf86f08
+SHA512:
+  metadata.gz: ca4d394affd9cc2904606404ff19e1a8954501865e85262d564784967aae6aaea8df9f65b58b95f8e04a8c6e2484162cfc725bda4da32ac19004e03e7447a40d
+  data.tar.gz: 9aa14fa9618d458371956c0d8cc29c1e1f188b53a5af4e19899cff28a7268f7aa6ac747fc5bc3dedd8857737ae0fbcde87183d227d6d400fed8557cc93c5e047

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+- First release: the `:duva` Action Mailer delivery method, built on `duva-mail`.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 9573-4562 Québec 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,89 @@
+# duva-rails
+
+Action Mailer delivery method for [Duva](https://duva.ca), the transactional email API hosted in Canada. Your mailers,
+`deliver_later` jobs and Devise emails go out through Duva with no change to your mailer code.
+
+Requires Ruby 3.3+ and Rails (Action Mailer) 7.2 to 8.x. Built on the official
+[`duva-mail`](https://rubygems.org/gems/duva-mail) library.
+
+## Install
+
+```ruby
+# Gemfile
+gem "duva-rails"
+```
+
+You also need a Duva API key and a verified domain ([documentation](https://duva.ca/en/docs)).
+
+## Configure
+
+```ruby
+# config/environments/production.rb
+config.action_mailer.delivery_method = :duva
+config.action_mailer.duva_settings = {
+  api_key: Rails.application.credentials.dig(:duva, :api_key), # or ENV["DUVA_API_KEY"]
+  domain: "example.com"                                         # or ENV["DUVA_DOMAIN"]
+}
+config.action_mailer.raise_delivery_errors = true
+```
+
+```ruby
+# app/mailers/application_mailer.rb
+default from: "Example <notifications@example.com>" # the address must belong to the Duva domain
+```
+
+Optional settings: `base_url` (default `https://api.duva.ca`), `timeout` (seconds, default 10), `max_retries` (default 2).
+`api_key` and `domain` fall back to the `DUVA_API_KEY` and `DUVA_DOMAIN` environment variables.
+
+## What is sent
+
+| Mail | Duva |
+|---|---|
+| From, To, Cc, Bcc, Reply-To | `from`, `to`, `cc`, `bcc`, `reply_to` (an address only in `smtp_envelope_to` is sent as Bcc) |
+| `text` and `html` parts, or a single-part body | `text`, `html` |
+| `attachments[...]`, `attachments.inline[...]` | `attachments` (inline ones keep their `content_id`) |
+| `List-Unsubscribe`, `List-Unsubscribe-Post`, `List-Id`, `In-Reply-To`, `References`, `Auto-Submitted`, `Precedence`, `Importance`, `Feedback-ID`, and `X-*` headers | `headers` |
+| `X-Duva-Tags`, `X-Duva-Metadata`, `X-Duva-Track`, `X-Idempotency-Key` | read by this gem, never sent (see below) |
+
+Duva-specific options are set as headers in the mailer:
+
+```ruby
+def welcome(user)
+  headers["X-Duva-Tags"] = "welcome, onboarding"               # tags
+  headers["X-Duva-Metadata"] = { user_id: user.id }.to_json    # metadata (JSON object)
+  headers["X-Duva-Track"] = "opens, clicks"                    # tracking (needs an HTML part)
+  headers["X-Idempotency-Key"] = "welcome-#{user.id}"          # see "Idempotency"
+  mail(to: user.email, subject: "Welcome")
+end
+```
+
+Notes:
+
+- Other headers are not forwarded (Duva rejects them), nor are `X-Duva*`, `X-Kumo*`, `X-Tenant*` and `X-Campaign*`.
+- A display name Duva refuses (it contains `@`, quotes, `<>`, control characters or an encoded word `=?…?=`) is dropped;
+  the address is kept.
+- Delivery is asynchronous: a successful `deliver_now` means Duva accepted the message, not that it was delivered. Use
+  Duva's webhooks or events for the outcome.
+- A Duva error (`Duva::Error` and its subclasses, from the `duva-mail` library) is raised from `deliver_now`, and
+  retried by Active Job in `deliver_later` according to your job configuration.
+
+### Idempotency
+
+A retried `deliver_later` job builds a new message, so a retry after a network timeout could send twice. Set a stable key
+for it (an order ID, for example) with the `X-Idempotency-Key` header. Duva ignores a second message with the same key.
+
+## Testing your application
+
+Use `ActionMailer::Base.delivery_method = :test` in your tests as usual. To exercise this gem without a network, give it
+the fake transport of the client library:
+
+```ruby
+transport = Duva::TestTransport.new { |_config, _spec| Duva::TestTransport.response("id" => "msg_...", "status" => "queued") }
+ActionMailer::Base.duva_settings = { api_key: "dv_test", domain: "example.com", transport: transport }
+# ... deliver ...
+transport.requests.last.body # what would have been sent
+```
+
+## License
+
+MIT.

data/duva-rails.gemspec

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "lib/duva/rails_version"
+
+Gem::Specification.new do |spec|
+  spec.name = "duva-rails"
+  spec.version = Duva::RAILS_VERSION
+  spec.summary = "Action Mailer delivery method for Duva, the transactional email API hosted in Canada."
+  spec.description = "Adds a :duva delivery method to Action Mailer: mailers, Active Job deliveries and " \
+                     "Action Mailbox replies are sent through Duva. Built on the official duva-mail library."
+  spec.authors = ["9573-4562 Québec inc."]
+  spec.email = ["support@duva.ca"]
+  spec.license = "MIT"
+  spec.homepage = "https://duva.ca"
+  spec.metadata = {
+    "source_code_uri" => "https://github.com/duva-mail/duva-rails",
+    "documentation_uri" => "https://duva.ca/en/docs",
+    "changelog_uri" => "https://github.com/duva-mail/duva-rails/blob/main/CHANGELOG.md",
+    "rubygems_mfa_required" => "true"
+  }
+  spec.required_ruby_version = ">= 3.3"
+  spec.files = Dir.glob("lib/**/*.rb") + ["README.md", "LICENSE", "CHANGELOG.md", "duva-rails.gemspec"]
+  spec.require_paths = ["lib"]
+  spec.add_dependency "actionmailer", ">= 7.2", "< 9"
+  spec.add_dependency "duva-mail", "~> 0.2"
+end

data/lib/duva/delivery_method.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Duva
+  # Action Mailer delivery method: sends a Mail::Message through the Duva API.
+  #
+  #   config.action_mailer.delivery_method = :duva
+  #   config.action_mailer.duva_settings = { api_key: ENV["DUVA_API_KEY"], domain: "example.com" }
+  #
+  # Settings: `api_key`, `domain` (both fall back to DUVA_API_KEY and DUVA_DOMAIN), `base_url`, `timeout`,
+  # `max_retries`; `transport:` takes a Duva::TestTransport in your own tests.
+  #
+  # Duva refuses a few things Mail allows, and this class translates rather than failing late: a display
+  # name Duva would reject is dropped (the address is kept), and only the headers Duva accepts are
+  # forwarded. The `X-Duva-*` headers below are read here and never sent.
+  class DeliveryMethod
+    # Duva's `headers` allowlist (docs/api.md); every other `X-*` is allowed except the reserved prefixes.
+    ALLOWED_HEADERS = %w[
+      list-unsubscribe list-unsubscribe-post list-id in-reply-to references auto-submitted precedence
+      importance feedback-id
+    ].freeze
+    RESERVED_PREFIXES = %w[x-kumo x-duva x-tenant x-campaign].freeze
+    # A name Duva refuses: `@`, quotes, angle brackets, backslash, control characters, encoded words.
+    UNSAFE_NAME = /[@"<>\\\u0000-\u001f\u007f]|=\?/
+    # A stable key so a retried job cannot send twice: read here, never forwarded.
+    IDEMPOTENCY_HEADER = "x-idempotency-key"
+
+    attr_accessor :settings
+
+    def initialize(settings = {})
+      @settings = settings
+    end
+
+    # Sends `mail`; returns the Duva::SendMessageResult (`id`, `status`, `replayed`) and sets the mail's
+    # Message-ID header to Duva's message id when it has none.
+    def deliver!(mail)
+      result = client.messages.deliver(**params(mail))
+      mail.message_id ||= result.id
+      result
+    end
+
+    private
+
+    def client
+      @client ||= Duva::Client.new(**client_options)
+    end
+
+    def client_options
+      options = settings.to_h.transform_keys(&:to_sym).slice(:api_key, :domain, :base_url, :timeout, :max_retries,
+                                                             :transport)
+      options.compact
+    end
+
+    def params(mail)
+      from = mail[:from]&.addrs&.first
+      raise ArgumentError, "Duva: the message has no From address" if from.nil?
+
+      { from: format_address(from), to: addresses(mail[:to]), subject: mail.subject.to_s }
+        .merge(copies(mail), bodies(mail), reply_to(mail), from_headers(mail), attachments(mail))
+    end
+
+    def copies(mail)
+      { cc: addresses(mail[:cc]), bcc: blind_copies(mail) }.reject { |_key, list| list.empty? }
+    end
+
+    def reply_to(mail)
+      address = mail[:reply_to]&.addrs&.first
+      address ? { reply_to: format_address(address) } : {}
+    end
+
+    def attachments(mail)
+      list = mail.attachments.map { |attachment| to_attachment(attachment) }
+      list.empty? ? {} : { attachments: list }
+    end
+
+    def addresses(field)
+      (field&.addrs || []).map { |address| format_address(address) }
+    end
+
+    # Recipients only in the envelope (explicit smtp_envelope_to) and the Bcc header are blind copies.
+    def blind_copies(mail)
+      listed = (mail[:to]&.addrs.to_a + mail[:cc]&.addrs.to_a).map { |a| a.address.downcase }
+      from_header = mail[:bcc]&.addrs.to_a
+      from_envelope = mail.smtp_envelope_to.to_a.map { |address| Mail::Address.new(address) }
+      (from_header + from_envelope).uniq { |a| a.address.downcase }
+                                   .reject { |a| listed.include?(a.address.downcase) }
+                                   .map { |a| format_address(a) }
+    end
+
+    # `Name <address>`, or the bare address when Duva would refuse the name.
+    def format_address(address)
+      name = address.display_name.to_s
+      return address.address if name.empty? || UNSAFE_NAME.match?(name)
+
+      Duva::Address.format(address.address, name)
+    end
+
+    def bodies(mail)
+      html = text = nil
+      if mail.multipart?
+        html = decode(mail.html_part)
+        text = decode(mail.text_part)
+      elsif mail.mime_type == "text/html"
+        html = decode(mail)
+      else
+        text = decode(mail)
+      end
+      { html: html, text: text }.compact
+    end
+
+    def decode(part)
+      return nil if part.nil?
+
+      body = part.body.decoded.to_s.dup.force_encoding(Encoding::UTF_8)
+      body = body.encode(Encoding::UTF_8, part.charset || "UTF-8", invalid: :replace, undef: :replace) unless body.valid_encoding?
+      body.empty? ? nil : body
+    end
+
+    # Headers, tags, metadata, tracking and the idempotency key, all read from the Mail headers.
+    def from_headers(mail)
+      out = {}
+      headers = {}
+      mail.header.fields.each do |field|
+        name = field.name.to_s
+        lower = name.downcase
+        value = field.value.to_s
+        case lower
+        when IDEMPOTENCY_HEADER then out[:idempotency_key] = value
+        when "x-duva-tags" then out[:tags] = value.split(",").map(&:strip).reject(&:empty?)
+        when "x-duva-metadata" then out[:metadata] = parse_metadata(value)
+        when "x-duva-track" then out[:tracking] = parse_tracking(value)
+        else headers[name] = value if forwardable?(lower)
+        end
+      end
+      out[:headers] = headers unless headers.empty?
+      out.reject { |_key, value| value.respond_to?(:empty?) && value.empty? }
+    end
+
+    # `X-Duva-Metadata: {"order_id": "42"}`. JSON, because Mail turns `_` into `-` in a header NAME.
+    def parse_metadata(value)
+      parsed = JSON.parse(value)
+      raise ArgumentError, "Duva: X-Duva-Metadata must be a JSON object" unless parsed.is_a?(Hash)
+
+      parsed.to_h { |key, entry| [key.to_s, entry.to_s] }
+    rescue JSON::ParserError
+      raise ArgumentError, "Duva: X-Duva-Metadata must be a JSON object"
+    end
+
+    # `X-Duva-Track: opens, clicks`
+    def parse_tracking(value)
+      wanted = value.split(",").map { |entry| entry.strip.downcase }
+      { opens: wanted.include?("opens"), clicks: wanted.include?("clicks") }
+    end
+
+    def forwardable?(lower)
+      return true if ALLOWED_HEADERS.include?(lower)
+
+      lower.start_with?("x-") && RESERVED_PREFIXES.none? { |prefix| lower.start_with?(prefix) }
+    end
+
+    def truthy?(value)
+      %w[true 1 yes on].include?(value.to_s.strip.downcase)
+    end
+
+    def to_attachment(attachment)
+      Duva::Attachments.from_bytes(
+        attachment.filename || "attachment", attachment.body.decoded,
+        content_type: attachment.mime_type, content_id: (attachment.cid if attachment.inline?)
+      )
+    end
+  end
+end

data/lib/duva/rails_version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Duva
+  RAILS_VERSION = "0.1.0"
+end

data/lib/duva/railtie.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Duva
+  # Registers the delivery method once Action Mailer is loaded, so `config.action_mailer.delivery_method = :duva`
+  # and `config.action_mailer.duva_settings = {...}` work in config/environments/*.rb.
+  #
+  # BEFORE `action_mailer.set_configs`: that initializer applies every `config.action_mailer.*` option to
+  # ActionMailer::Base, and `duva_settings=` only exists once the delivery method is registered.
+  class Railtie < ::Rails::Railtie
+    initializer "duva.add_delivery_method", before: "action_mailer.set_configs" do
+      ActiveSupport.on_load(:action_mailer) do
+        add_delivery_method :duva, Duva::DeliveryMethod
+      end
+    end
+  end
+end

data/lib/duva-rails.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "action_mailer"
+require "duva"
+require_relative "duva/rails_version"
+require_relative "duva/delivery_method"
+require_relative "duva/railtie" if defined?(Rails::Railtie)
+
+# Registers the :duva delivery method with Action Mailer. Outside a Rails application (a plain
+# Action Mailer script), `ActionMailer::Base.add_delivery_method` is called here directly.
+ActionMailer::Base.add_delivery_method(:duva, Duva::DeliveryMethod) unless defined?(Rails::Railtie)

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: duva-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- 9573-4562 Québec inc.
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-09 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: duva-mail
+  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'
+description: 'Adds a :duva delivery method to Action Mailer: mailers, Active Job deliveries
+  and Action Mailbox replies are sent through Duva. Built on the official duva-mail
+  library.'
+email:
+- support@duva.ca
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- duva-rails.gemspec
+- lib/duva-rails.rb
+- lib/duva/delivery_method.rb
+- lib/duva/rails_version.rb
+- lib/duva/railtie.rb
+homepage: https://duva.ca
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/duva-mail/duva-rails
+  documentation_uri: https://duva.ca/en/docs
+  changelog_uri: https://github.com/duva-mail/duva-rails/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.3'
+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: Action Mailer delivery method for Duva, the transactional email API hosted
+  in Canada.
+test_files: []