rails_mailersend 0.4.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 877745c41ce75703b82b4b6dc8bbb34630a510a193d51b5ce55ebb65451d3545
-  data.tar.gz: 872bb9d2cf47dd7d9ee90e7f5f899157822b09bfbb6b3aad3f3ea028a9fe79bf
+  metadata.gz: f3615a45b8f5ec8f462c1a590064cd923ff3e5ede15dcfa3470aeb83077a7858
+  data.tar.gz: 8f67af0e86500603cc5216f2504d06a4b3f7ba6b4903e270b3e3df59076be672
 SHA512:
-  metadata.gz: aacb555e2d9c009d1225661ab1146e6c15257fb5b0687678c12a8a95f47929eb672b89e5df3b142b65c0d6aaddd0188252ffde4bb093c7d1bd1a34e46215a899
-  data.tar.gz: 3843ec66ec35a363ca0f0f1f4592a75cb866833b8c20d09e9c7a9ab64c37bb1e833fc791ac590cf37847f7c43636b79d6bb42cd85ecc6e2a309bffdfd5c3dcb9
+  metadata.gz: d443297aedd5a29abb72ad9ef7bb74cd021bdb208e1998fde63c2e3553bb8951f4249a80cf723a2b3008cc2185960937361c6a7d83a90afca94ff8835bdcebfb
+  data.tar.gz: b40dc56a2d2322607c25d51df1a2eb18af3b0cafeff698944a863631c43dbc548d278a00c7e31e5273bc17416c9a3f68aca99c32a0f0ea7c5e2ab9b63f915625

data/README.md

@@ -65,6 +65,55 @@ than returning quietly, so the enqueuing job retries and the failure is visible.
 For an app where sign-in is by magic link, a swallowed delivery error looks
 exactly like a broken app to the person waiting.
 
+`In-Reply-To` and `References` are carried across to MailerSend's own
+`in_reply_to` and `references` fields, so a reply lands under the message it
+answers instead of opening a conversation of its own:
+
+```ruby
+mail(to: person.email_address, subject: "Re: #{parent_subject}",
+     in_reply_to: parent_message_id, references: [parent_message_id])
+```
+
+Angle brackets are put back on, since the `mail` gem strips them and MailerSend
+validates against the RFC 5322 form. Every other header is dropped: the API takes
+fields rather than a MIME message, and these are the two worth translating. Both
+are paid-plan only at MailerSend, which answers a free account carrying them with
+a 422 — loudly, rather than with an unthreaded reply nobody can account for.
+
+## Link and open tracking
+
+MailerSend can rewrite every link in a message to a redirector on its own domain. For
+marketing mail that is the point. For a message carrying a credential it is two problems at
+once: the token is handed to a third party and kept in their click reporting, and the
+rewritten URL is no longer yours — so an iOS Universal Link stops matching your
+`apple-app-site-association` and opens a browser instead of your app. For a single-use
+sign-in link that means it is spent somewhere the app cannot see it.
+
+Set the switches per message, on the mailer that needs them:
+
+```ruby
+class SessionMailer < ApplicationMailer
+  def sign_in(user)
+    headers["X-MailerSend-Track-Clicks"] = "false"
+    mail to: user.email, subject: "Your sign-in link"
+  end
+end
+```
+
+| Header | MailerSend field |
+|---|---|
+| `X-MailerSend-Track-Clicks` | `settings.track_clicks` |
+| `X-MailerSend-Track-Opens` | `settings.track_opens` |
+| `X-MailerSend-Track-Content` | `settings.track_content` |
+
+Each takes `"true"` or `"false"`, case-insensitively. A message that sets none says nothing
+about tracking, and MailerSend falls back to the domain's own setting — so this changes
+nothing for the mail you already send.
+
+A value that is neither raises, rather than being quietly dropped. The caller asking for
+tracking off is usually sending a credential, and the failure mode of guessing is a token
+routed through a redirector without anybody noticing.
+
 ## Inbound mail
 
 Optional, and only loads when the app has Action Mailbox. MailerSend posts the

data/lib/mailersend_rails/delivery_method.rb

@@ -29,6 +29,24 @@ module MailersendRails
     OPEN_TIMEOUT = 15
     READ_TIMEOUT = 30
 
+    # MailerSend's per-message tracking switches, and the header each is set from.
+    #
+    # Tracking rewrites every link in the message to a redirector on MailerSend's
+    # domain. For marketing mail that is the point. For a message carrying a
+    # credential it is two problems: the token is handed to a third party and
+    # logged in their click reporting, and the rewritten URL is no longer yours --
+    # so an iOS Universal Link stops matching your apple-app-site-association and
+    # opens a browser instead of your app, which for a single-use sign-in link
+    # means it is spent somewhere the app cannot see.
+    #
+    # Absent means absent: MailerSend falls back to the domain's own setting, so a
+    # message that says nothing keeps whatever the account is configured for.
+    TRACKING = {
+      "track_clicks" => "X-MailerSend-Track-Clicks",
+      "track_opens" => "X-MailerSend-Track-Opens",
+      "track_content" => "X-MailerSend-Track-Content"
+    }.freeze
+
     attr_reader :settings
 
     def initialize(settings = {})
@@ -55,10 +73,63 @@ module MailersendRails
           "reply_to" => Array(mail.reply_to).empty? ? {} : address_in(mail[:reply_to]),
           "subject" => mail.subject,
           "text" => mail.text_part&.body&.decoded,
-          "html" => html_for(mail)
+          "html" => html_for(mail),
+          "in_reply_to" => message_ids_in(mail[:in_reply_to]).first,
+          "references" => message_ids_in(mail[:references]),
+          "settings" => tracking_in(mail)
         }.reject { |_, value| omit?(value) }
       end
 
+      # The tracking switches this message sets, if any. See TRACKING.
+      #
+      # A value that is neither "true" nor "false" raises rather than being
+      # dropped, for the same reason a failed delivery raises: the caller that
+      # asked for tracking off is usually sending a credential, and the failure
+      # mode of guessing is a token quietly routed through a redirector. A typo
+      # here is a mistake in the sender's own code and shows up the first time
+      # that mailer is exercised.
+      def tracking_in(mail)
+        TRACKING.each_with_object({}) do |(field, header), settings|
+          raw = mail[header]&.to_s&.strip
+          next if raw.nil? || raw.empty?
+
+          case raw.downcase
+          when "true" then settings[field] = true
+          when "false" then settings[field] = false
+          else raise DeliveryError, "#{header} must be \"true\" or \"false\", got #{raw.inspect}"
+          end
+        end
+      end
+
+      # In-Reply-To and References, in the form MailerSend asks for them.
+      #
+      # Threading is what puts a reply under the message it answers rather than
+      # in a conversation of its own, and these two headers are the whole of it.
+      # They need carrying by hand because the API takes fields rather than a
+      # MIME message: every header Action Mailer set that isn't named in
+      # #payload_for is dropped here, and a mailer that sets In-Reply-To and
+      # then watches its reply arrive as a new thread has nowhere to look for
+      # where it went. Both fields are paid-plan only at MailerSend, which
+      # answers a request carrying them on a free account with a 422 -- loudly,
+      # like every other delivery failure.
+      #
+      # The `mail` gem hands ids back with the angle brackets stripped and
+      # MailerSend validates against the RFC 5322 form, so they go back on. A
+      # field too malformed to parse falls back to splitting on whitespace,
+      # which is the shape of both headers.
+      def message_ids_in(field)
+        return [] if field.nil?
+
+        ids = field.respond_to?(:message_ids) ? field.message_ids : field.to_s.split
+        Array(ids).filter_map { |id| bracketed(id) }
+      end
+
+      def bracketed(id)
+        id = id.to_s.strip.delete_prefix("<").delete_suffix(">").strip
+
+        "<#{id}>" unless id.empty?
+      end
+
       def html_for(mail)
         mail.html_part&.body&.decoded || mail.body.decoded
       end

data/lib/mailersend_rails/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MailersendRails
-  VERSION = "0.4.1"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_mailersend
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Dan Loman