feat: add message token to return path for bounce tracking

Adds the message token to the return path (MAIL FROM) to enable faster
bounce message matching. When use_message_tags_for_bounces is enabled,
bounces can be matched by extracting the token from the return path
instead of scanning the entire message body.

Format: server_token+message_token@return_path_domain

Cherry-picked from postalserver/postal PR postalserver#3036

Co-authored-by: schueffi <schueffi@users.noreply.github.com>
Co-authored-by: openhands <openhands@all-hands.dev>

Author: openhands-agent

app/senders/smtp_sender.rb

@@ -142,10 +142,10 @@ def determine_mail_from_for_message(message)
     # If the domain has a valid custom return path configured, return
     # that.
     if message.domain.return_path_status == "OK"
-      return "#{message.server.token}@#{message.domain.return_path_domain}"
+      return "#{message.server.token}+#{message.token}@#{message.domain.return_path_domain}"
     end
 
-    "#{message.server.token}@#{Postal::Config.dns.return_path_domain}"
+    "#{message.server.token}+#{message.token}@#{Postal::Config.dns.return_path_domain}"
   end
 
   # Return the RCPT TO to use for the given message in this sending session

doc/config/yaml.yml

@@ -23,6 +23,8 @@ postal:
   use_local_ns_for_domain_verification: false
   # Append a Resend-Sender header to all outgoing e-mails
   use_resent_sender_header: true
+  # Use message tags when assigning bounces to their corresponding messages
+  use_message_tags_for_bounces: false
   # The default size for new DKIM keys
   default_dkim_key_size: 1024
   # Path to the private key used for signing

lib/postal/config_schema.rb

@@ -66,6 +66,11 @@ module Postal
         default true
       end
 
+      boolean :use_message_tags_for_bounces do
+        description "Use message tags when assigning bounces to their corresponding messages"
+        default false
+      end
+
       integer :default_dkim_key_size do
         description "The default size for new DKIM keys"
         default 1024

lib/postal/message_db/message.rb

@@ -511,7 +511,17 @@ def create_link(url)
       def original_messages
         return nil unless bounce
 
-        other_message_ids = raw_message.scan(/\X-Postal-MsgID:\s*([a-z0-9]+)/i).flatten
+        # if this is enabled, we search first for the message tag as this is faster
+        # than to scan the full message (which is probably many mbytes in size)
+        if Postal::Config.postal.use_message_tags_for_bounces?
+          uname, domain = rcpt_to.split("@", 2)
+          uname, other_message_ids = uname.split("+", 2)
+        end
+        # if we did not found any messages, or this was not enabled, then fall back to
+        # the old header based search
+        if other_message_ids.nil? || other_message_ids.empty?
+          other_message_ids = raw_message.scan(/\X-Postal-MsgID:\s*([a-z0-9]+)/i).flatten
+        end
         if other_message_ids.empty?
           []
         else