helo-email-sdk 1.0.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: afb5076cf98aa9c91576e55fe946cd31ec2c3db4f2c1b7d9fa57d1d0f73a39e7
-  data.tar.gz: 404f3097b870c14fb708f09509eee2663a42b50bfb20f262a868c22a0188a5e7
+  metadata.gz: 28a1530bbcbb83039f3b9ad42de952e4304dcd84f928968e9eddfcdac0a14087
+  data.tar.gz: 831fc165e69374debae288d5c55d7046683c8cbdb30b550e656f55609b0ceeb3
 SHA512:
-  metadata.gz: 25922786dfda9de69a3941b1b6ae32c9a92f8a84b53404d90d29632374cab2683f65410c05775a5bed9920020b04cd10ace4cd890b926a2d043b37f41f73470f
-  data.tar.gz: 4915fa1d5b7ea81981887177c13dfc43dda6384cc84d86ba2f32e239e83db459bdfaef08cb1ffe0fcbaee2977a772d40da3c9562771080dcdcdf02511b6b449c
+  metadata.gz: 9addab2c0ddcd644ed94886ef93b7f32ebe84431987ebb96dee85b017cb6a6c2acf960c4ec57f4eda6d30dede78e18e3e85edd98ce8a525daaa8119069621364
+  data.tar.gz: 287062d7c0942f5e50904a1d3748e4e03127a53f4811d53d58930ca490bf926a636ddc0bca8efe4aee6cccc4cb2ecca17bcd09b8c0430f9d3ff277443b75b5fe

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
@@ -122,4 +167,5 @@ To compute a signature yourself — signing a fixture in tests, for example —
 - [Helo::Broadcasts](docs/Broadcasts.md)
 - [Helo::Statistics](docs/Statistics.md)
 - [Helo::Suppressions](docs/Suppressions.md)
+- [Helo::Templates](docs/Templates.md)
 - [Helo::Webhooks](docs/Webhooks.md)

data/lib/helo/apis/templates.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Helo
+  class Templates < API
+    def list(request_data = {})
+      request = TemplatesListRequest.new(request_data)
+      response = @client.request(:get, "/templates", params: request.to_params)
+      PaginatedResponseOfTemplateSummaryResponse.from_hash(response.body)
+    end
+
+    def create(request_data)
+      request = CreateTemplateRequest.new(request_data)
+      response = @client.request(:post, "/templates", body: request.to_params)
+      TemplateResponse.from_hash(response.body)
+    end
+
+    def render_draft(request_data)
+      request = RenderDraftRequest.new(request_data)
+      response = @client.request(:post, "/templates/render", body: request.to_params)
+      RenderTemplateResponse.from_hash(response.body)
+    end
+
+    def retrieve(id)
+      response = @client.request(:get, "/templates/#{id}")
+      TemplateResponse.from_hash(response.body)
+    end
+
+    def update(id, request_data)
+      request = UpdateTemplateRequest.new(request_data)
+      response = @client.request(:patch, "/templates/#{id}", body: request.to_params)
+      TemplateResponse.from_hash(response.body)
+    end
+
+    def delete(id)
+      response = @client.request(:delete, "/templates/#{id}")
+      nil
+    end
+
+    def render(id, request_data)
+      request = RenderTemplateRequest.new(request_data)
+      response = @client.request(:post, "/templates/#{id}/render", body: request.to_params)
+      RenderTemplateResponse.from_hash(response.body)
+    end
+
+    class_methods :list, :create, :render_draft, :retrieve, :update, :delete, :render
+  end
+end

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/create_domain_request.rb

@@ -6,5 +6,6 @@ module Helo
 
     api_attribute :name, :string, key: "name"
     api_attribute :channel_ids, key: "channelIds"
+    api_attribute :enable_custom_tracking, :boolean, key: "enableCustomTracking"
   end
 end

data/lib/helo/models/create_template_request.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Helo
+  class CreateTemplateRequest
+    include Helo::Core::Model
+
+    api_attribute :name, :string, key: "name"
+    api_attribute :subject, :string, key: "subject"
+    api_attribute :html, :string, key: "html"
+    api_attribute :mjml, :string, key: "mjml"
+    api_attribute :text, :string, key: "text"
+    api_attribute :channel_ids, key: "channelIds"
+  end
+end

data/lib/helo/models/dns_records_response.rb

@@ -7,5 +7,6 @@ module Helo
     api_attribute :domain_key_active, Helo::Core::ModelType.new("Helo::DnsRecordResponse"), key: "domainKeyActive"
     api_attribute :domain_key_pending, Helo::Core::ModelType.new("Helo::DnsRecordResponse"), key: "domainKeyPending"
     api_attribute :return_path, Helo::Core::ArrayType.new("Helo::DnsRecordResponse"), key: "returnPath"
+    api_attribute :tracking, Helo::Core::ModelType.new("Helo::DnsRecordResponse"), key: "tracking"
   end
 end

data/lib/helo/models/paginated_response_of_template_summary_response.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Helo
+  class PaginatedResponseOfTemplateSummaryResponse
+    include Helo::Core::Model
+
+    api_attribute :total_count, :integer, key: "totalCount"
+    api_attribute :results, Helo::Core::ArrayType.new("Helo::TemplateSummaryResponse"), key: "results"
+  end
+end

data/lib/helo/models/render_draft_request.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Helo
+  class RenderDraftRequest
+    include Helo::Core::Model
+
+    api_attribute :subject, :string, key: "subject"
+    api_attribute :html, :string, key: "html"
+    api_attribute :mjml, :string, key: "mjml"
+    api_attribute :text, :string, key: "text"
+    api_attribute :inline_styles, :boolean, key: "inlineStyles"
+    api_attribute :data, key: "data"
+  end
+end

data/lib/helo/models/render_template_request.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Helo
+  class RenderTemplateRequest
+    include Helo::Core::Model
+
+    api_attribute :inline_styles, :boolean, key: "inlineStyles"
+    api_attribute :data, key: "data"
+  end
+end

data/lib/helo/models/render_template_response.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Helo
+  class RenderTemplateResponse
+    include Helo::Core::Model
+
+    api_attribute :subject, :string, key: "subject"
+    api_attribute :html, :string, key: "html"
+    api_attribute :text, :string, key: "text"
+  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/models/template_response.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Helo
+  class TemplateResponse
+    include Helo::Core::Model
+
+    api_attribute :id, :string, key: "id"
+    api_attribute :created_at, :datetime, key: "createdAt"
+    api_attribute :updated_at, :datetime, key: "updatedAt"
+    api_attribute :version, :integer, key: "version"
+    api_attribute :name, :string, key: "name"
+    api_attribute :subject, :string, key: "subject"
+    api_attribute :html, :string, key: "html"
+    api_attribute :mjml, :string, key: "mjml"
+    api_attribute :text, :string, key: "text"
+    api_attribute :channel_ids, key: "channelIds"
+  end
+end

data/lib/helo/models/template_summary_response.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Helo
+  class TemplateSummaryResponse
+    include Helo::Core::Model
+
+    api_attribute :id, :string, key: "id"
+    api_attribute :created_at, :datetime, key: "createdAt"
+    api_attribute :updated_at, :datetime, key: "updatedAt"
+    api_attribute :name, :string, key: "name"
+    api_attribute :subject, :string, key: "subject"
+    api_attribute :channel_ids, key: "channelIds"
+  end
+end

data/lib/helo/models/templates_list_request.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Helo
+  # Generated request model for query parameters
+  class TemplatesListRequest
+    include Helo::Core::Model
+
+    api_attribute :limit, :integer, key: "limit"
+    api_attribute :offset, :integer, key: "offset"
+    api_attribute :name, :string, key: "name"
+    api_attribute :channel_ids, key: "channelIds", explode: false
+  end
+end

data/lib/helo/models/update_domain_request.rb

@@ -5,5 +5,6 @@ module Helo
     include Helo::Core::Model
 
     api_attribute :channel_ids, key: "channelIds"
+    api_attribute :enable_custom_tracking, :boolean, key: "enableCustomTracking"
   end
 end

data/lib/helo/models/update_template_request.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Helo
+  class UpdateTemplateRequest
+    include Helo::Core::Model
+
+    api_attribute :name, :string, key: "name"
+    api_attribute :subject, :string, key: "subject"
+    api_attribute :html, :string, key: "html", nullable: true
+    api_attribute :mjml, :string, key: "mjml", nullable: true
+    api_attribute :text, :string, key: "text", nullable: true
+    api_attribute :channel_ids, key: "channelIds", nullable: true
+    api_attribute :version, :integer, key: "version"
+  end
+end

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.2.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.2.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
@@ -97,6 +111,7 @@ files:
 - lib/helo/apis/sending.rb
 - lib/helo/apis/statistics.rb
 - lib/helo/apis/suppressions.rb
+- lib/helo/apis/templates.rb
 - lib/helo/apis/webhooks.rb
 - lib/helo/client.rb
 - lib/helo/configuration.rb
@@ -117,6 +132,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
@@ -146,6 +162,7 @@ files:
 - lib/helo/models/create_domain_request.rb
 - lib/helo/models/create_suppressions_request.rb
 - lib/helo/models/create_suppressions_response.rb
+- lib/helo/models/create_template_request.rb
 - lib/helo/models/create_webhook_request.rb
 - lib/helo/models/delivered_details.rb
 - lib/helo/models/delivery_stats.rb
@@ -183,6 +200,7 @@ files:
 - lib/helo/models/paginated_response_of_broadcast_suppression.rb
 - lib/helo/models/paginated_response_of_domain_response.rb
 - lib/helo/models/paginated_response_of_suppression_response.rb
+- lib/helo/models/paginated_response_of_template_summary_response.rb
 - lib/helo/models/pagination_result_of_channel_basic_response.rb
 - lib/helo/models/pagination_result_of_webhook_response.rb
 - lib/helo/models/recipient_complained_webhook_payload.rb
@@ -193,6 +211,9 @@ files:
 - lib/helo/models/remove_suppression_result.rb
 - lib/helo/models/remove_suppressions_request.rb
 - lib/helo/models/remove_suppressions_response.rb
+- lib/helo/models/render_draft_request.rb
+- lib/helo/models/render_template_request.rb
+- lib/helo/models/render_template_response.rb
 - lib/helo/models/resubscribed_details.rb
 - lib/helo/models/return_path_domain_verification_failed_payload.rb
 - lib/helo/models/return_path_domain_verified_payload.rb
@@ -220,10 +241,14 @@ files:
 - lib/helo/models/suppression_response.rb
 - lib/helo/models/suppression_result.rb
 - lib/helo/models/suppressions_list_request.rb
+- lib/helo/models/template_response.rb
+- lib/helo/models/template_summary_response.rb
+- lib/helo/models/templates_list_request.rb
 - lib/helo/models/unsubscribed_details.rb
 - lib/helo/models/update_channel_request.rb
 - lib/helo/models/update_channel_tracking.rb
 - lib/helo/models/update_domain_request.rb
+- lib/helo/models/update_template_request.rb
 - lib/helo/models/update_webhook_request.rb
 - lib/helo/models/validation_error.rb
 - lib/helo/models/webhook_header.rb
@@ -231,6 +256,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