SendGrid: Handle non-string data in legacy substitutions

SendGrid returns a cryptic "Bad Request" error (with no other details) when legacy
substitutions values are anything other than string or null. (This only applies
to substitutions, for legacy templates and on-the-fly merge fields.)

Convert numeric types to string (per Anymail's documented `merge_data` behavior),
and raise an AnymailSerializationError for other unsupported substitutions values.

Fixes #420

Author: medmunds

CHANGELOG.rst

@@ -56,6 +56,13 @@ Fixes
 * **Postmark:** Fix an error in inbound handling with long email address display
   names that include non-ASCII characters.
 
+* **SendGrid:** Improve handling of non-string values in ``merge_data`` when using
+  legacy templates or inline merge fields. To avoid a confusing SendGrid API error
+  message, Anymail now converts numeric merge data values to strings, but will raise
+  an AnymailSerializationError for other non-string data in SendGrid substitutions.
+  (SendGrid's newer *dynamic* transactional templates do not have this limitation.)
+  (Thanks to `@PlusAsh`_ for reporting the issue.)
+
 Other
 ~~~~~
 
@@ -1798,6 +1805,7 @@ Features
 .. _@mwheels: https://github.com/mwheels
 .. _@nuschk: https://github.com/nuschk
 .. _@originell: https://github.com/originell
+.. _@PlusAsh: https://github.com/PlusAsh
 .. _@puru02: https://github.com/puru02
 .. _@RignonNoel: https://github.com/RignonNoel
 .. _@rodrigondec: https://github.com/rodrigondec

anymail/backends/sendgrid.py

@@ -3,7 +3,11 @@
 
 from requests.structures import CaseInsensitiveDict
 
-from ..exceptions import AnymailConfigurationError, AnymailWarning
+from ..exceptions import (
+    AnymailConfigurationError,
+    AnymailSerializationError,
+    AnymailWarning,
+)
 from ..message import AnymailRecipientStatus
 from ..utils import BASIC_NUMERIC_TYPES, Mapping, get_anymail_setting, update_deep
 from .base_requests import AnymailRequestsBackend, RequestsPayload
@@ -159,6 +163,20 @@ def convert_dynamic_template_data_to_legacy_substitutions(self):
         """
         Change personalizations[...]['dynamic_template_data'] to ...['substitutions]
         """
+
+        def transform_substitution_value(value):
+            # SendGrid substitutions must be string or null, or SendGrid issues the
+            # cryptic error `{"field": null, "message": "Bad Request", "help": null}`.
+            # Anymail will convert numbers; treat anything else as an error.
+            if isinstance(value, str) or value is None:
+                return value
+            if isinstance(value, BASIC_NUMERIC_TYPES):
+                return str(value)
+            raise AnymailSerializationError(
+                "SendGrid legacy substitutions require string values."
+                f" Don't know how to handle {type(value).__name__}."
+            )
+
         merge_field_format = self.merge_field_format or "{}"
 
         all_merge_fields = set()
@@ -171,7 +189,7 @@ def convert_dynamic_template_data_to_legacy_substitutions(self):
                 # Convert dynamic_template_data keys for substitutions,
                 # using merge_field_format
                 personalization["substitutions"] = {
-                    merge_field_format.format(field): data
+                    merge_field_format.format(field): transform_substitution_value(data)
                     for field, data in dynamic_template_data.items()
                 }
                 all_merge_fields.update(dynamic_template_data.keys())

tests/test_sendgrid_backend.py

@@ -831,6 +831,56 @@ def test_legacy_warn_if_no_global_merge_field_delimiters(self):
         with self.assertWarnsRegex(AnymailWarning, r"SENDGRID_MERGE_FIELD_FORMAT"):
             self.message.send()
 
+    def test_legacy_data_conversion(self):
+        """
+        SendGrid requires string (or null) substitution values.
+        Anymail will convert numbers.
+        """
+        # (Legacy substitutions path because not using dynamic template id.)
+        self.message.to = ["alice@example.com"]
+        self.message.merge_data = {
+            "alice@example.com": {
+                ":integer": 1,
+                ":float": 1.0,
+                ":null": None,
+            }
+        }
+        self.message.send()
+        data = self.get_api_call_json()
+        self.assertEqual(
+            data["personalizations"][0]["substitutions"],
+            {
+                ":integer": "1",
+                ":float": "1.0",
+                ":null": None,
+            },
+        )
+
+    def test_legacy_unsupported_string_conversion(self):
+        """
+        SendGrid requires string substitution values (and issues a cryptic
+        error otherwise). Anymail treats non-convertible data as an error.
+        """
+        # (Legacy substitutions path because not using dynamic template id.)
+        self.message.to = ["alice@example.com"]
+        cases = [
+            ["array"],
+            {"dict": 1},
+            Decimal("1.0"),
+        ]
+        for case in cases:
+            with self.subTest(case=case):
+                self.message.merge_data = {
+                    "alice@example.com": {
+                        ":value": case,
+                    }
+                }
+                with self.assertRaisesMessage(
+                    AnymailSerializationError,
+                    "SendGrid legacy substitutions require string values",
+                ):
+                    self.message.send()
+
     def test_merge_metadata(self):
         self.message.to = ["alice@example.com", "Bob <bob@example.com>"]
         self.message.merge_metadata = {