Add merge_headers option for Amazon SES

Add new `merge_headers` message option 
for per-recipient headers with template sends. 

* Support in base backend
* Implement in Amazon SES backend
  (Requires boto3 >= 1.34.98.)

---------

Co-authored-by: Mike Edmunds <medmunds@gmail.com>

anymail/backends/amazon_ses.py

@@ -298,6 +298,9 @@ class AmazonSESV2SendEmailPayload(AmazonSESBasePayload):
         # metadata.
         self.mime_message["X-Metadata"] = self.serialize_json(metadata)
 
+    def set_merge_headers(self, merge_headers):
+        self.unsupported_feature("merge_headers without template_id")
+
     def set_tags(self, tags):
         # See note about Amazon SES Message Tags and custom headers in set_metadata
         # above. To support reliable retrieval in webhooks, use custom headers for tags.
@@ -339,6 +342,7 @@ class AmazonSESV2SendBulkEmailPayload(AmazonSESBasePayload):
         # late-bind recipients and merge_data in finalize_payload
         self.recipients = {"to": [], "cc": [], "bcc": []}
         self.merge_data = {}
+        self.merge_headers = {}
 
     def finalize_payload(self):
         # Build BulkEmailEntries from recipients and merge_data.
@@ -355,8 +359,9 @@ class AmazonSESV2SendBulkEmailPayload(AmazonSESBasePayload):
             ]
 
         # Construct an entry with merge data for each "to" recipient:
-        self.params["BulkEmailEntries"] = [
-            {
+        self.params["BulkEmailEntries"] = []
+        for to in self.recipients["to"]:
+            entry = {
                 "Destination": dict(ToAddresses=[to.address], **cc_and_bcc_addresses),
                 "ReplacementEmailContent": {
                     "ReplacementTemplate": {
@@ -366,8 +371,13 @@ class AmazonSESV2SendBulkEmailPayload(AmazonSESBasePayload):
                     }
                 },
             }
-            for to in self.recipients["to"]
-        ]
+
+            if len(self.merge_headers) > 0:
+                entry["ReplacementHeaders"] = [
+                    {"Name": key, "Value": value}
+                    for key, value in self.merge_headers.get(to.addr_spec, {}).items()
+                ]
+            self.params["BulkEmailEntries"].append(entry)
 
     def parse_recipient_status(self, response):
         try:
@@ -490,6 +500,10 @@ class AmazonSESV2SendBulkEmailPayload(AmazonSESBasePayload):
         # late-bound in finalize_payload
         self.merge_data = merge_data
 
+    def set_merge_headers(self, merge_headers):
+        # late-bound in finalize_payload
+        self.merge_headers = merge_headers
+
     def set_merge_global_data(self, merge_global_data):
         # DefaultContent.Template.TemplateData
         self.params.setdefault("DefaultContent", {}).setdefault("Template", {})[

anymail/backends/base.py

@@ -286,6 +286,7 @@ class BasePayload:
         ("template_id", last, force_non_lazy),
         ("merge_data", merge_dicts_one_level, force_non_lazy_dict),
         ("merge_global_data", merge_dicts_shallow, force_non_lazy_dict),
+        ("merge_headers", None, None),
         ("merge_metadata", merge_dicts_one_level, force_non_lazy_dict),
         ("esp_extra", merge_dicts_deep, force_non_lazy_dict),
     )
@@ -293,7 +294,7 @@ class BasePayload:
 
     # If any of these attrs are set on a message, treat the message
     # as a batch send (separate message for each `to` recipient):
-    batch_attrs = ("merge_data", "merge_metadata")
+    batch_attrs = ("merge_data", "merge_headers", "merge_metadata")
 
     def __init__(self, message, defaults, backend):
         self.message = message
@@ -617,6 +618,9 @@ class BasePayload:
     def set_merge_data(self, merge_data):
         self.unsupported_feature("merge_data")
 
+    def set_merge_headers(self, merge_headers):
+        self.unsupported_feature("merge_headers")
+
     def set_merge_global_data(self, merge_global_data):
         self.unsupported_feature("merge_global_data")
 

anymail/backends/test.py

@@ -147,6 +147,9 @@ class TestPayload(BasePayload):
     def set_merge_data(self, merge_data):
         self.params["merge_data"] = merge_data
 
+    def set_merge_headers(self, merge_headers):
+        self.params["merge_headers"] = merge_headers
+
     def set_merge_metadata(self, merge_metadata):
         self.params["merge_metadata"] = merge_metadata
 

anymail/message.py

@@ -29,6 +29,7 @@ class AnymailMessageMixin(EmailMessage):
         self.template_id = kwargs.pop("template_id", UNSET)
         self.merge_data = kwargs.pop("merge_data", UNSET)
         self.merge_global_data = kwargs.pop("merge_global_data", UNSET)
+        self.merge_headers = kwargs.pop("merge_headers", UNSET)
         self.merge_metadata = kwargs.pop("merge_metadata", UNSET)
         self.anymail_status = AnymailStatus()