helo-email-sdk 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: afb5076cf98aa9c91576e55fe946cd31ec2c3db4f2c1b7d9fa57d1d0f73a39e7
-  data.tar.gz: 404f3097b870c14fb708f09509eee2663a42b50bfb20f262a868c22a0188a5e7
+  metadata.gz: 24f067959418c6bacc218f81802bbcbda0eacedd25e5bc16f156c4e6e7ef2192
+  data.tar.gz: 1ee808b62e899e0df4a98e9c24385f5045df97daba11d55301a3312fb064bb03
 SHA512:
-  metadata.gz: 25922786dfda9de69a3941b1b6ae32c9a92f8a84b53404d90d29632374cab2683f65410c05775a5bed9920020b04cd10ace4cd890b926a2d043b37f41f73470f
-  data.tar.gz: 4915fa1d5b7ea81981887177c13dfc43dda6384cc84d86ba2f32e239e83db459bdfaef08cb1ffe0fcbaee2977a772d40da3c9562771080dcdcdf02511b6b449c
+  metadata.gz: b06dc543d3d8773f415b3d0413c5524006742af0a6a6cb74a750a8e4ac9a552f83e24d631917b84cafb3810022694e953ab7a3034d6e6ab40a16d724afddd389
+  data.tar.gz: f07bba17cd695cb7728cef33bc396222c78208d541c0e331a15e8abff22b9beb77ee3bfdc4c00ae539618343ab994265822e8239294041c54f09be33d4a1a9bb

data/README.md

@@ -25,7 +25,6 @@ require "helo-email-sdk"
 
 Helo.configure do |config|
   config.api_key = ENV.fetch("HELO_API_KEY")
-  config.base_url = "https://api.helohq.com" # optional, this is the default
 end
 ```
 
@@ -60,6 +59,52 @@ rescue Helo::APIError => e
 end
 ```
 
+## Rails (ActionMailer)
+
+The gem registers a `:helo` delivery method with ActionMailer, so existing
+mailers send through the API without any changes. Configure the SDK in an initializer:
+
+```ruby
+# config/initializers/helo.rb
+Helo.configure do |config|
+  config.api_key = Rails.application.credentials.helo_api_key
+end
+```
+
+and switch the delivery method:
+
+```ruby
+# config/environments/production.rb
+config.action_mailer.delivery_method = :helo
+```
+
+Plain ActionMailer fields map to the API: `from`, `to`, `cc`, `bcc`, `reply_to`, `subject`, the
+text and HTML parts, attachments (`attachments.inline` ones keep their content id, so
+`image_tag attachments["logo.png"].url` works), and any custom headers. API-specific options go
+in `delivery_method_options`, which other delivery methods (`:test`, letter_opener, SMTP) ignore:
+
+```ruby
+class UserMailer < ApplicationMailer
+  def welcome(user)
+    headers["X-Custom-Header"] = "value" # custom headers are sent as-is
+    mail(
+      to: user.email,
+      subject: "Welcome!",
+      delivery_method_options: {
+        tags: ["welcome"],
+        metadata: { user_id: user.id.to_s },
+        tracking: { opens: true, links: false },
+        idempotency_key: "welcome-#{user.id}", # retries won't send twice
+        channel_id: "..."
+      }
+    )
+  end
+end
+```
+
+After delivery, `message[:helo_message_id].value` is the id the API assigned the
+message, and failed requests raise `Helo::APIError` (subject to `config.action_mailer.raise_delivery_errors`).
+
 ## Webhook signature verification
 
 Webhook deliveries are signed with the endpoint's signing key. Verify every delivery before

data/lib/helo/mailer.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Helo
+  # ActionMailer delivery method, registered as :helo by the Railtie.
+  class Mailer
+    STANDARD_HEADERS = %w[
+      from to cc bcc reply-to subject date message-id mime-version
+      content-type content-transfer-encoding content-disposition content-id
+      sender return-path
+    ].freeze
+
+    # Where the API's id for the message is recorded after sending
+    MESSAGE_ID_FIELD = "helo-message-id"
+
+    attr_reader :settings
+
+    # Receives mail(delivery_method_options: { ... }) as settings. return_response makes
+    # Mail::Message#deliver! return our response.
+    def initialize(settings = {})
+      @settings = settings.merge(return_response: true)
+    end
+
+    def deliver!(mail)
+      raise ArgumentError, "Helo is not configured: call Helo.configure" unless API.default_client
+
+      response = Sending.send_transactional(
+        build_request(mail),
+        channel_id: settings[:channel_id],
+        idempotency_key: settings[:idempotency_key]
+      )
+      if response&.message_id
+        mail[MESSAGE_ID_FIELD] = nil # Mail would otherwise add a second field when resending
+        mail[MESSAGE_ID_FIELD] = response.message_id
+      end
+      response
+    end
+
+    private
+
+    def build_request(mail)
+      {
+        from: addresses(mail[:from]).first,
+        to: addresses(mail[:to]),
+        cc: addresses(mail[:cc]),
+        bcc: addresses(mail[:bcc]),
+        reply_to: addresses(mail[:reply_to]),
+        subject: mail.subject,
+        html: body(mail, "text/html"),
+        text: body(mail, "text/plain"),
+        attachments: attachments(mail),
+        headers: custom_headers(mail),
+        tags: settings[:tags],
+        metadata: settings[:metadata],
+        tracking: settings[:tracking]
+      }.compact_blank
+    end
+
+    def addresses(field)
+      return [] unless field
+      raise ArgumentError, "Invalid #{field.name} address: #{field.value}" unless field.respond_to?(:addrs)
+
+      field.addrs.map { |address| { email: address.address, name: address.display_name }.compact }
+    end
+
+    def body(mail, mime_type)
+      if mail.multipart?
+        part = mime_type == "text/html" ? mail.html_part : mail.text_part
+        part&.decoded
+      elsif (mail.mime_type || "text/plain") == mime_type
+        mail.decoded
+      end
+    end
+
+    def attachments(mail)
+      mail.attachments.map do |attachment|
+        {
+          content: [attachment.decoded].pack("m0"),
+          file_name: attachment.filename,
+          content_type: attachment.mime_type,
+          disposition: attachment.inline? ? "inline" : "attachment",
+          content_id: (attachment.cid if attachment.inline?)
+        }.compact
+      end
+    end
+
+    def custom_headers(mail)
+      mail.header_fields.each_with_object({}) do |field, headers|
+        next if STANDARD_HEADERS.include?(field.name.downcase) || field.name.downcase == MESSAGE_ID_FIELD
+
+        headers[field.name] = field.value.to_s
+      end
+    end
+  end
+end

data/lib/helo/models/send_broadcast_request_template.rb

@@ -4,6 +4,7 @@ module Helo
   class SendBroadcastRequestTemplate
     include Helo::Core::Model
 
+    api_attribute :id, :string, key: "id"
     api_attribute :subject, :string, key: "subject"
     api_attribute :html, :string, key: "html"
     api_attribute :text, :string, key: "text"

data/lib/helo/models/send_message_request_template.rb

@@ -4,6 +4,7 @@ module Helo
   class SendMessageRequestTemplate
     include Helo::Core::Model
 
+    api_attribute :id, :string, key: "id"
     api_attribute :subject, :string, key: "subject"
     api_attribute :html, :string, key: "html"
     api_attribute :text, :string, key: "text"

data/lib/helo/railtie.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Helo
+  class Railtie < ::Rails::Railtie
+    ActiveSupport.on_load(:action_mailer) do
+      add_delivery_method :helo, Helo::Mailer
+    end
+  end
+end

data/lib/helo/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Helo
-  VERSION = "1.0.1"
+  VERSION = "1.1.0"
 end

data/lib/helo.rb

@@ -18,6 +18,8 @@ require_relative "helo/api_error"
 require_relative "helo/configuration"
 require_relative "helo/client"
 require_relative "helo/webhook_signatures"
+require_relative "helo/mailer"
+require_relative "helo/railtie" if defined?(Rails::Railtie)
 
 
 module Helo

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: helo-email-sdk
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Helo Email
@@ -37,6 +37,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: actionmailer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -117,6 +131,7 @@ files:
 - lib/helo/enums/message_status.rb
 - lib/helo/enums/suppression_reason.rb
 - lib/helo/enums/webhook_event.rb
+- lib/helo/mailer.rb
 - lib/helo/models/activity_event.rb
 - lib/helo/models/activity_list_events_request.rb
 - lib/helo/models/activity_list_messages_request.rb
@@ -231,6 +246,7 @@ files:
 - lib/helo/models/webhook_payload_common.rb
 - lib/helo/models/webhook_response.rb
 - lib/helo/models/webhooks_list_request.rb
+- lib/helo/railtie.rb
 - lib/helo/version.rb
 - lib/helo/webhook_signatures.rb
 homepage: https://rubygems.org/gems/helo-email-sdk