letterapp 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f34428952a2c04f306b6202d26e5fed5537a347aef6b5682d893eacd2b5d148c
-  data.tar.gz: f21c70172c12e83daf530971113ae379c385b18a2101189546c97cd1c978d70e
+  metadata.gz: 0f2fde121f30391e8ef7d0272b8b8ca855d13f8597f90618ca493969eef045c2
+  data.tar.gz: 2647178c2d51cb3edbf7aace4aa8c71343321434107d5d55c06e8d75407a05f0
 SHA512:
-  metadata.gz: 04155060eef72dc6631a404abf9ea37327a7584642d576f52e43245c1d95729c31a60728589fd750839ddd8c5279b5d8e3bc7bfafc8316042f33fbde0ff0021b
-  data.tar.gz: a91ef9c7620135df31e75a05b4164b78e17feae3630f89b14f17a92e36e87a0d0dde7fd9ceb57abf5b38ae3746f28f9dd1f7b0f34111399531121d7c4a60ccd0
+  metadata.gz: d5b5f7fa5a456b68b32659ffa690f3550e6f6ae618be9f54cab3462d7e2676d31eaf2ebe75a1ab09c04fc0525ae813fc2c7cece6a25f3ea472efbb317df0dafe
+  data.tar.gz: cfc610d764cf25e18d0894f14bc440613a72945ebc5441d3bb1d86d706832f4f6b28401581fdc6b3fddcbaa381514e8ad9d599c594ef3bb14877c33fc213d691

data/README.md

@@ -48,14 +48,78 @@ def handler(event:, context:)
 end
 ```
 
+## Transactional email
+
+`send_email` mails one person right now: a receipt, a password reset, a
+verification link. It is never batched and never waits for `flush`.
+
+```ruby
+result = letter.send_email(
+  to: "alice@example.com",
+  subject: "Reset your password",
+  html: "<p>Click <a href='https://...'>here</a> to reset.</p>",
+  tag: "password-reset",
+  idempotency_key: "password-reset:#{token}"
+)
+
+result["messageId"] # provider id, appears in delivery events
+```
+
+It's `send_email` and not `send` because `Object#send` is Ruby's dynamic
+dispatch; shadowing it would break metaprogramming in the host app.
+
+Only `to:`, `subject:` and one of `html:` / `text:` are required. `from:`
+defaults to the project's sender and must be on a verified domain. A
+plain-text part is derived from the HTML when you don't supply one.
+
+Pass an `idempotency_key:` whenever the call can be retried (a job with
+retries, a webhook handler): a replay returns the original send rather than
+mailing the recipient twice, and it's what lets the SDK retry a `5xx` safely.
+
+Failures raise `Letterapp::Error` with `#status`, `#code` and `#reason`. The
+reason is what tells "this recipient is unreachable" apart from "our account
+is blocked":
+
+```ruby
+begin
+  letter.send_email(to: to, subject: subject, html: html)
+rescue Letterapp::Error => e
+  raise unless e.reason == "suppressed" # hard-bounced or complained; nothing to fix
+end
+```
+
+Transactional mail ignores marketing unsubscribes (an opted-out user still
+gets their password reset) but respects bounces, complaints, and addresses
+suppressed by hand.
+
+### Rails
+
+The gem registers `:letter` as an ActionMailer delivery method, so switching
+providers is two lines of config. Every existing mailer, view, and
+`deliver_later` keeps working unchanged.
+
+```ruby
+# config/environments/production.rb
+config.action_mailer.delivery_method = :letter
+config.action_mailer.letter_settings = { api_key: ENV["LETTER_API_KEY"] }
+```
+
+HTML and text parts map straight through. A message with several recipients
+becomes one send each, so everyone gets their own log row and bounce.
+Attachments raise, rather than being dropped silently, since the transactional
+API doesn't carry them.
+
 ## What it does
 
-- **Auto-batching** - calls are queued and flushed every 100ms or 50 events by
-  a background thread.
+- **Auto-batching** - `identify` / `group` / `track` are queued and flushed
+  every 100ms or 50 events by a background thread. `send_email` always goes out
+  immediately.
 - **Retries** - `429` waits `Retry-After`; `5xx` and network errors back off
-  exponentially with jitter, up to `max_retries` (default 3).
-- **Idempotent** - every call gets a UUID `message_id` so retries are
-  deduplicated server-side.
+  exponentially with jitter, up to `max_retries` (default 3). A `send_email`
+  without an `idempotency_key` is never retried, since a duplicate email is
+  worse than a failed one.
+- **Idempotent** - every ingestion call gets a UUID `message_id` so retries are
+  deduplicated server-side; `send_email` takes your own key.
 - **No dependencies** - HTTP over the standard library `net/http`.
 
 ## API
@@ -75,18 +139,22 @@ Letterapp::Client.new(
 letter.identify(user_id:, email: nil, traits: nil, timezone: nil, timestamp: nil, message_id: nil)
 letter.group(user_id:, account_id:, name: nil, traits: nil, timestamp: nil, message_id: nil)
 letter.track(user_id:, event:, properties: nil, timestamp: nil, message_id: nil)
+letter.send_email(to:, subject:, html: nil, text: nil, from: nil, from_name: nil,
+                  reply_to: nil, headers: nil, tag: nil, metadata: nil,
+                  idempotency_key: nil) # => Hash, sent immediately
 letter.flush # send queued calls now, block until done
 letter.close # flush + stop the background thread (also runs at exit)
 ```
 
 Configuration errors and non-retryable API responses raise `Letterapp::Error`
-(with `#status` and `#body`). Background transport errors are passed to
-`on_error` instead, since they cannot be raised to the caller.
+(with `#status`, `#code`, `#reason` and `#body`). Background transport errors
+are passed to `on_error` instead, since they cannot be raised to the caller.
 
 ## Full documentation
 
 - **SDK reference:** <https://letter.app/docs/ruby-sdk>
 - **Ingestion API:** <https://letter.app/docs/api>
+- **Transactional API:** <https://letter.app/docs/transactional>
 
 ## License
 

data/lib/letterapp/client.rb

@@ -12,23 +12,36 @@ module Letterapp
   DEFAULT_BASE_URL = "https://api.letter.app"
 
   # Raised for client misconfiguration and non-retryable API errors.
+  #
+  # +code+ is the API's machine-readable error code (bad_request, forbidden,
+  # ...). +reason+ is the finer-grained cause when a send was refused
+  # (suppressed, account_suspended, email_quota_exceeded, daily_cap,
+  # billing_required, provider_rejected), which is what tells "this one
+  # recipient is unreachable" apart from "our account is blocked".
   class Error < StandardError
-    attr_reader :status, :body
+    attr_reader :status, :body, :code, :reason
 
-    def initialize(message, status: nil, body: nil)
+    def initialize(message, status: nil, body: nil, payload: nil)
       super(message)
       @status = status
       @body = body
+      error = payload.is_a?(Hash) ? (payload["error"] || {}) : {}
+      @code = error["code"]
+      @reason = error["reason"]
     end
   end
 
-  # A Letter ingestion client.
+  # A Letter client.
   #
   # Long-running server (default): identify / group / track enqueue calls that a
   # background thread auto-batches and flushes every 100ms or 50 events. Call
   # +close+ before the process exits.
   #
   # Serverless: pass flush_at: 1 and call +flush+ at the end of each invocation.
+  #
+  # +send_email+ (transactional) sits outside that machinery: it always performs
+  # the request and returns the result. Batching a password reset would be a
+  # bug, not an optimization.
   class Client
     # @param api_key   [String] API key (Dashboard -> Settings -> API keys).
     # @param base_url  [String] API origin. Defaults to https://api.letter.app.
@@ -78,6 +91,38 @@ module Letterapp
       enqueue(serialize_track(user_id, event, properties, timestamp, message_id))
     end
 
+    # Send one transactional email and return the parsed result Hash
+    # ("id", "messageId", "status", "replayed", ...).
+    #
+    # Named +send_email+ rather than +send+ because Object#send is Ruby's
+    # dynamic dispatch: shadowing it on a client object would break every
+    # +client.send(:private_method)+ and metaprogramming call in the host app.
+    #
+    # Never queued: the call performs the request and returns once the provider
+    # has accepted the message. Pass +idempotency_key+ wherever the call can be
+    # retried (a job with retries, a webhook handler): a replay returns the
+    # original send rather than mailing the recipient twice, and it is what
+    # makes retrying a 5xx safe. Without one this method does not retry,
+    # because a duplicate email is worse than a failed one.
+    #
+    # +from+ defaults to the project's sender and must be on a verified domain.
+    def send_email(to:, subject:, html: nil, text: nil, from: nil, from_name: nil,
+                   reply_to: nil, headers: nil, tag: nil, metadata: nil,
+                   idempotency_key: nil)
+      raise Error, "send_email: to is required" if blank?(to)
+      raise Error, "send_email: subject is required" if blank?(subject)
+      raise Error, "send_email: provide html, text, or both" if blank?(html) && blank?(text)
+
+      body = { "to" => to, "subject" => subject }
+      {
+        "html" => html, "text" => text, "from" => from, "fromName" => from_name,
+        "replyTo" => reply_to, "headers" => headers, "tag" => tag,
+        "metadata" => metadata, "idempotencyKey" => idempotency_key
+      }.each { |key, value| body[key] = value unless value.nil? }
+
+      request("/v1/send", body, max_retries: idempotency_key ? @max_retries : 0) || {}
+    end
+
     # Send everything currently queued and block until it completes.
     def flush
       loop do
@@ -140,30 +185,37 @@ module Letterapp
       @on_error.call(e.is_a?(Error) ? e : Error.new(e.message))
     end
 
-    def request(path, body)
+    # POST +body+ to +path+, returning the decoded JSON response (or nil for an
+    # empty one). +max_retries+ defaults to the client setting; callers pass 0
+    # for requests that are not replay-safe (see +send_email+).
+    def request(path, body, max_retries: @max_retries)
       data = JSON.generate(body)
       last_err = nil
 
-      (0..@max_retries).each do |attempt|
+      (0..max_retries).each do |attempt|
         begin
           res = post(path, data)
           code = res.code.to_i
-          return if code >= 200 && code < 300
+          return decode_json(res.body) if code >= 200 && code < 300
 
-          if code == 429 && attempt < @max_retries
+          if code == 429 && attempt < max_retries
             sleep(retry_after(res))
             next
           end
-          if code >= 500 && attempt < @max_retries
+          if code >= 500 && attempt < max_retries
             sleep(backoff(attempt))
             next
           end
+
+          payload = decode_json(res.body)
+          message = payload&.dig("error", "message") || res.body
           raise Error.new(
-            "Request failed with #{code}: #{res.body}", status: code, body: res.body
+            "Request failed with #{code}: #{message}",
+            status: code, body: res.body, payload: payload
           )
         rescue Timeout::Error, IOError, SystemCallError, SocketError => e
           last_err = Error.new("Network error: #{e.message}")
-          raise last_err if attempt >= @max_retries
+          raise last_err if attempt >= max_retries
 
           sleep(backoff(attempt))
         end
@@ -172,6 +224,15 @@ module Letterapp
       raise(last_err || Error.new("Request failed for unknown reason"))
     end
 
+    def decode_json(raw)
+      return nil if raw.nil? || raw.empty?
+
+      parsed = JSON.parse(raw)
+      parsed.is_a?(Hash) ? parsed : nil
+    rescue JSON::ParserError
+      nil
+    end
+
     def post(path, data)
       http = Net::HTTP.new(@uri.host, @uri.port)
       http.use_ssl = (@uri.scheme == "https")

data/lib/letterapp/delivery_method.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require_relative "client"
+
+module Letterapp
+  # ActionMailer delivery method backed by Letter's transactional API.
+  #
+  # Register it and every existing mailer, view and `deliver_later` keeps
+  # working unchanged - Rails builds the same Mail::Message it always did, and
+  # this class is only responsible for putting it on the wire:
+  #
+  #   # config/initializers/letter.rb
+  #   ActionMailer::Base.add_delivery_method :letter, Letterapp::DeliveryMethod
+  #
+  #   # config/environments/production.rb
+  #   config.action_mailer.delivery_method = :letter
+  #   config.action_mailer.letter_settings = { api_key: ENV["LETTER_API_KEY"] }
+  #
+  # Multipart mail maps cleanly: Letter takes an HTML part and a text part, and
+  # a Mail::Message carries exactly those two. Attachments and inline images do
+  # not map, and we raise rather than silently dropping them, since a receipt
+  # that arrives without its PDF looks delivered but isn't.
+  #
+  # One recipient per API call. A mail addressed to several people becomes
+  # several sends, which is also what you want: each recipient gets their own
+  # log row, their own bounce, and can't see the others.
+  #
+  # To make a delivery replay-safe, set the idempotency key in the mailer:
+  #
+  #   headers["X-Letter-Idempotency-Key"] = "password-reset:#{token}"
+  #
+  # The header is consumed here, not forwarded. It has to come from the mailer
+  # because it must be derived from what you are sending about; Message-ID
+  # can't stand in for it, since ActionMailer rebuilds the message (and so
+  # generates a fresh Message-ID) every time a `deliver_later` job retries.
+  class DeliveryMethod
+    IDEMPOTENCY_HEADER = "X-Letter-Idempotency-Key"
+
+    # ActionMailer instantiates this with the configured settings hash and
+    # reads `#settings` back when merging defaults.
+    attr_accessor :settings
+
+    def initialize(settings = {})
+      @settings = settings || {}
+    end
+
+    def deliver!(mail)
+      html, text = bodies(mail)
+      if html.nil? && text.nil?
+        raise Error, "Letter delivery: message has no text or HTML body"
+      end
+
+      unless mail.attachments.empty?
+        raise Error,
+              "Letter delivery: attachments are not supported by the " \
+              "transactional API (#{mail.attachments.map(&:filename).join(', ')})"
+      end
+
+      recipients = Array(mail.to) + Array(mail.cc) + Array(mail.bcc)
+      raise Error, "Letter delivery: message has no recipients" if recipients.empty?
+
+      base_key = mail[IDEMPOTENCY_HEADER]&.value&.to_s
+      headers = custom_headers(mail)
+
+      recipients.map do |to|
+        client.send_email(
+          to: to,
+          subject: mail.subject.to_s,
+          html: html,
+          text: text,
+          from: address_of(mail.from),
+          from_name: display_name_of(mail[:from]),
+          reply_to: address_of(mail.reply_to),
+          headers: headers,
+          tag: settings[:tag],
+          # Scoped per recipient: the same message to three people is three
+          # distinct sends, not one replayed twice.
+          idempotency_key: base_key && !base_key.empty? ? "#{base_key}:#{to}" : nil
+        )
+      end
+    end
+
+    private
+
+    def client
+      @client ||= Client.new(
+        api_key: settings.fetch(:api_key) { ENV.fetch("LETTER_API_KEY") },
+        base_url: settings[:base_url] || ENV["LETTER_BASE_URL"] || DEFAULT_BASE_URL,
+        # This client only ever calls send_email, which bypasses the queue, so
+        # the batching thread would sit idle forever. Setting flush_at to 1
+        # keeps it from being started for nothing.
+        flush_at: 1
+      )
+    end
+
+    def bodies(mail)
+      if mail.multipart?
+        [mail.html_part&.decoded, mail.text_part&.decoded]
+      elsif mail.mime_type == "text/html"
+        [mail.body.decoded, nil]
+      else
+        [nil, mail.body.decoded]
+      end
+    end
+
+    # Headers Rails or Mail generate for the envelope, which Letter sets itself
+    # from the fields above. Passing them through would be rejected as reserved
+    # or would produce duplicates.
+    ENVELOPE_HEADERS = %w[
+      from to cc bcc subject reply-to date message-id mime-version
+      content-type content-transfer-encoding
+    ].freeze
+
+    def custom_headers(mail)
+      skip = ENVELOPE_HEADERS + [IDEMPOTENCY_HEADER.downcase]
+      headers = {}
+      mail.header.fields.each do |field|
+        name = field.name.to_s
+        next if skip.include?(name.downcase)
+
+        headers[name] = field.value.to_s
+      end
+      headers.empty? ? nil : headers
+    end
+
+    def address_of(field)
+      Array(field).first
+    end
+
+    def display_name_of(field)
+      field&.display_names&.compact&.first
+    end
+  end
+end

data/lib/letterapp/railtie.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+require_relative "delivery_method"
+
+module Letterapp
+  # Registers `:letter` as an ActionMailer delivery method so a Rails app only
+  # has to pick it:
+  #
+  #   config.action_mailer.delivery_method = :letter
+  #   config.action_mailer.letter_settings = { api_key: ENV["LETTER_API_KEY"] }
+  #
+  # Loaded from letterapp.rb only when Rails is present, so the gem stays
+  # dependency-free everywhere else.
+  class Railtie < ::Rails::Railtie
+    initializer "letterapp.add_delivery_method" do
+      ActiveSupport.on_load(:action_mailer) do
+        add_delivery_method :letter, Letterapp::DeliveryMethod
+      end
+    end
+  end
+end

data/lib/letterapp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Letterapp
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/letterapp.rb

@@ -2,6 +2,12 @@
 
 require_relative "letterapp/version"
 require_relative "letterapp/client"
+require_relative "letterapp/delivery_method"
+
+# In a Rails app, register `:letter` as an ActionMailer delivery method so the
+# host only has to select it. Guarded so the gem keeps working (and stays
+# dependency-free) outside Rails.
+require_relative "letterapp/railtie" if defined?(::Rails::Railtie)
 
 # Official Ruby client for letter.app.
 #
@@ -10,6 +16,7 @@ require_relative "letterapp/client"
 #   letter = Letterapp::Client.new(api_key: ENV["LETTER_API_KEY"])
 #   letter.identify(user_id: "user_123", email: "alice@example.com")
 #   letter.track(user_id: "user_123", event: "Signed Up")
+#   letter.send_email(to: "alice@example.com", subject: "Hi", html: "<p>Hi</p>")
 #   letter.close
 module Letterapp
   # Convenience: Letterapp.new(...) == Letterapp::Client.new(...)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: letterapp
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - letter.app
@@ -9,8 +9,9 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: 'Auto-batching Ruby client for letter.app: identify users, track events,
-  and group accounts over the ingestion API. Retries, idempotency, zero runtime dependencies.'
+description: 'Ruby client for letter.app: send transactional email (with an ActionMailer
+  delivery method), identify users, track events, and group accounts. Auto-batching,
+  retries, idempotency, zero runtime dependencies.'
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -19,6 +20,8 @@ files:
 - README.md
 - lib/letterapp.rb
 - lib/letterapp/client.rb
+- lib/letterapp/delivery_method.rb
+- lib/letterapp/railtie.rb
 - lib/letterapp/version.rb
 homepage: https://letter.app/docs/ruby-sdk
 licenses:
@@ -44,5 +47,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.4
 specification_version: 4
-summary: Official Ruby client for letter.app - onboarding email drip campaigns.
+summary: Official Ruby client for letter.app - transactional email and onboarding
+  drip campaigns.
 test_files: []