Allow sanitise_content_for arg in send_email_notification endpoint

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 12.1.0
+
+* Adds `sanitise_content_for` parameter to `send_email_notification` endpoint. See [our documentation](https://docs.notifications.service.gov.uk/python.html#reducing-the-risk-of-malicious-content-injection-in-placeholders) for guidance on how to use this.
+
 ## 12.0.0
 
 * Drop support for end-of-life Python 3.9

integration_test/integration_tests.py

@@ -60,9 +60,11 @@ def send_email_notification_test_response(python_client, reply_to=None):
         personalisation=personalisation,
         one_click_unsubscribe_url=one_click_unsubscribe_url,
         email_reply_to_id=email_reply_to_id,
+        sanitise_content_for=["name"],
     )
     validate(response, post_email_response)
-    assert unique_name in response["content"]["body"]  # check placeholders are replaced
+    # check placeholders are replaced and sanitised:
+    assert unique_name.replace("-", "\\-") in response["content"]["body"]
     return response["id"]
 
 

integration_test/schemas/v2/notification_schemas.py

@@ -115,7 +115,7 @@
     },
     "required": ["id", "content", "uri", "template"],
 }
-
+# TODO: this doesn't seem to be used anywhere, do we still need it?
 post_email_request = {
     "$schema": "http://json-schema.org/draft-04/schema#",
     "description": "POST email notification schema",
@@ -128,6 +128,7 @@
         "email_reply_to_id": uuid,
         "personalisation": personalisation,
         "one_click_unsubscribe_url": https_url,
+        "sanitise_content_for": {"type": "array", "items": {"type": "string"}},
     },
     "required": ["email_address", "template_id"],
 }
@@ -156,8 +157,9 @@
         "content": email_content,
         "uri": {"type": "string"},
         "template": template,
+        "sanitised_content": {"type": "object"},
     },
-    "required": ["id", "content", "uri", "template"],
+    "required": ["id", "content", "uri", "template", "sanitised_content"],
 }
 
 post_letter_request = {
@@ -217,13 +219,15 @@ def create_post_sms_response_from_notification(notification, body, from_number,
     }
 
 
+# TODO: we don't seem to be using this, is it needed?
 def create_post_email_response_from_notification(notification, content, subject, email_from, url_root):
     return {
         "id": notification.id,
         "reference": notification.client_reference,
         "content": {"from_email": email_from, "body": content, "subject": subject},
         "uri": f"{url_root}/v2/notifications/{str(notification.id)}",
         "template": __create_template_from_notification(notification=notification, url_root=url_root),
+        "sanitised_content": {},
     }
 
 

notifications_python_client/__init__.py

@@ -7,7 +7,7 @@
 #
 # -- http://semver.org/
 
-__version__ = "12.0.0"
+__version__ = "12.1.0"
 
 from notifications_python_client.errors import (  # noqa
     REQUEST_ERROR_MESSAGE,

notifications_python_client/notifications.py

@@ -29,6 +29,7 @@ def send_email_notification(
         reference=None,
         email_reply_to_id=None,
         one_click_unsubscribe_url=None,
+        sanitise_content_for=None,
     ):
         notification = {"email_address": email_address, "template_id": template_id}
         if personalisation:
@@ -39,6 +40,8 @@ def send_email_notification(
             notification.update({"email_reply_to_id": email_reply_to_id})
         if one_click_unsubscribe_url:
             notification.update({"one_click_unsubscribe_url": one_click_unsubscribe_url})
+        if sanitise_content_for:
+            notification.update({"sanitise_content_for": sanitise_content_for})
 
         return self.post("/v2/notifications/email", data=notification)
 

tests/notifications_python_client/test_notifications_api_client.py

@@ -174,6 +174,25 @@ def test_create_email_notification_with_personalisation(notifications_client, rm
     }
 
 
+def test_create_email_notification_with_sanitise_content_for(notifications_client, rmock):
+    endpoint = f"{TEST_HOST}/v2/notifications/email"
+    rmock.request("POST", endpoint, json={"status": "success"}, status_code=200)
+
+    notifications_client.send_email_notification(
+        email_address="to@example.com",
+        template_id="456",
+        personalisation={"name": "chris", "link": "https://www.safe-link.gov.uk"},
+        sanitise_content_for=["name"],
+    )
+
+    assert rmock.last_request.json() == {
+        "template_id": "456",
+        "email_address": "to@example.com",
+        "personalisation": {"name": "chris", "link": "https://www.safe-link.gov.uk"},
+        "sanitise_content_for": ["name"],
+    }
+
+
 def test_create_email_notification_with_one_click_unsubscribe_url(notifications_client, rmock):
     endpoint = f"{TEST_HOST}/v2/notifications/email"
     rmock.request("POST", endpoint, json={"status": "success"}, status_code=200)