NHSDigital · Kennedy1265 · Jul 9, 2025 · Jul 10, 2025 · Jul 10, 2025 · Jul 15, 2025
diff --git a/docs/tests/post_v1_message-batches/happy_path.md b/docs/tests/post_v1_message-batches/happy_path.md
@@ -3,6 +3,24 @@
 ## 201 - Success
 
 
+### Scenario: An API consumer creating a message that has a terminal status of FAILED
+
+**Given** the API consumer provides details for an unreachable recipient in their new message
+<br/>
+**When** the request is submitted
+<br/>
+**Then** the response is a 201 success
+<br/>
+
+**Asserts**
+- Response returns a 201 status code
+- Response body matches expected result
+- Response contains correctly formatted link to new message URI
+- Message in NHS Notify reaches terminal status of FAILED
+- Message has expected failure reason and code
+- Channel has expected failure reason and code
+
+
 ### Scenario: An API consumer creating a batch of messages with an undefined NHS number receives a 201 response
 
 **Given** the API consumer does not provide an NHS number for a recipient in their new message batch and the allowAnonymousPatient flag is set to true

diff --git a/docs/tests/post_v1_single-message/happy_path.md b/docs/tests/post_v1_single-message/happy_path.md
@@ -3,6 +3,24 @@
 These tests target the API endpoint POST /v1/messages testing successful responses when valid data is provided.
 
 
+## Scenario: An API consumer creating a message that has a terminal status of FAILED
+
+**Given** the API consumer provides details for an unreachable recipient in their new message
+<br/>
+**When** the request is submitted
+<br/>
+**Then** the response is a 201 success
+<br/>
+
+**Asserts**
+- Response returns a 201 status code
+- Response body matches expected result
+- Response contains correctly formatted link to new message URI
+- Message in NHS Notify reaches terminal status of FAILED
+- Message has expected failure reason and code
+- Channel has expected failure reason and code
+
+
 ## Scenario: An API consumer creating a message with an undefined NHS number receives a 201 response
 
 **Given** the API consumer does not provide an NHS number for the recipient in their new message and the allowAnonymousPatient flag is set to true

diff --git a/proxies/live/apiproxy/targets/target.xml b/proxies/live/apiproxy/targets/target.xml
@@ -18,10 +18,14 @@
         <SSLInfo>
             <Enabled>true</Enabled>
         </SSLInfo>
-        <LoadBalancer>
-            <Server name="{{ TARGET_SERVER_OVERRIDE | default('communications-manager-target') }}"/>
-        </LoadBalancer>
-        <Path>{requestpath}</Path>
+        {% if ENVIRONMENT_TYPE == 'sandbox' %}
+            <LoadBalancer>
+                <Server name="{{ TARGET_SERVER_OVERRIDE | default('communications-manager-target') }}"/>
+            </LoadBalancer>
+            <Path>{requestpath}</Path>
+        {% else %}
+            <URL>https://comms-apim.de-rake4.communications.national.nhs.uk</URL>
+        {% endif %}
         <Properties>
             <Property name="io.timeout.millis">29000</Property>
         </Properties>

diff --git a/proxies/shared/policies/AssignMessage.MessageBatches.Create.Request.xml b/proxies/shared/policies/AssignMessage.MessageBatches.Create.Request.xml
@@ -16,10 +16,17 @@
         <Name>target.copy.pathsuffix</Name>
         <Value>false</Value>
     </AssignVariable>
-    <AssignVariable>
-        <Name>requestpath</Name>
-        <Value>/api/v1/send</Value>
-    </AssignVariable>
+    {% if ENVIRONMENT_TYPE == 'sandbox' %}
+       <AssignVariable>
+           <Name>requestpath</Name>
+           <Value>/api/v1/send</Value>
+       </AssignVariable>
+    {% else %}
+        <AssignVariable>
+            <Name>target.url</Name>
+            <Value>https://comms-apim.de-rake4.communications.national.nhs.uk/api/v1/send</Value>
+        </AssignVariable>
+    {% endif %}
     <Set>
         <Payload contentType="application/json" variablePrefix="%" variableSuffix="#">%data.payload#</Payload>
         <Headers>

diff --git a/proxies/shared/policies/AssignMessage.Messages.Create.Request.xml b/proxies/shared/policies/AssignMessage.Messages.Create.Request.xml
@@ -16,10 +16,17 @@
         <Name>target.copy.pathsuffix</Name>
         <Value>false</Value>
     </AssignVariable>
-    <AssignVariable>
-        <Name>requestpath</Name>
-        <Value>/api/v1/messages</Value>
-    </AssignVariable>
+    {% if ENVIRONMENT_TYPE == 'sandbox' %}
+       <AssignVariable>
+           <Name>requestpath</Name>
+           <Value>/api/v1/messages</Value>
+       </AssignVariable>
+    {% else %}
+        <AssignVariable>
+            <Name>target.url</Name>
+            <Value>https://comms-apim.de-rake4.communications.national.nhs.uk/api/v1/messages</Value>
+        </AssignVariable>
+    {% endif %}
     <Set>
         <Payload contentType="application/json" variablePrefix="%" variableSuffix="#">%data.payload#</Payload>
         <Headers>

diff --git a/proxies/shared/policies/AssignMessage.Messages.GetSingle.Request.xml b/proxies/shared/policies/AssignMessage.Messages.GetSingle.Request.xml
@@ -16,10 +16,17 @@
         <Name>target.copy.pathsuffix</Name>
         <Value>false</Value>
     </AssignVariable>
-    <AssignVariable>
-        <Name>requestpath</Name>
-        <Template>/api/v1/messages/{data.messageId}</Template>
-    </AssignVariable>
+    {% if ENVIRONMENT_TYPE == 'sandbox' %}
+       <AssignVariable>
+           <Name>requestpath</Name>
+           <Template>/api/v1/messages/{data.messageId}</Template>
+       </AssignVariable>
+    {% else %}
+        <AssignVariable>
+            <Name>target.url</Name>
+            <Value>https://comms-apim.de-rake4.communications.national.nhs.uk/api/v1/messages/{data.messageId}</Value>
+        </AssignVariable>
+    {% endif %}
     <Set>
         <Headers>
             <Header name="X-Correlation-Id">{backendCorrelationId}</Header>

diff --git a/proxies/shared/policies/AssignMessage.NhsAppAccounts.Get.Request.xml b/proxies/shared/policies/AssignMessage.NhsAppAccounts.Get.Request.xml
@@ -16,10 +16,17 @@
         <Name>target.copy.pathsuffix</Name>
         <Value>false</Value>
     </AssignVariable>
-    <AssignVariable>
-        <Name>requestpath</Name>
-        <Value>/api/channels/nhsapp/accounts</Value>
-    </AssignVariable>
+    {% if ENVIRONMENT_TYPE == 'sandbox' %}
+       <AssignVariable>
+           <Name>requestpath</Name>
+           <Value>/api/channels/nhsapp/accounts</Value>
+       </AssignVariable>
+    {% else %}
+        <AssignVariable>
+            <Name>target.url</Name>
+            <Value>https://comms-apim.de-rake4.communications.national.nhs.uk/api/channels/nhsapp/accounts</Value>
+        </AssignVariable>
+    {% endif %}
     <Set>
         <Headers>
             <Header name="X-Correlation-Id">{backendCorrelationId}</Header>

diff --git a/sandbox/messages/2WL45YuHOLATvC3GspEu0oSioux.json b/sandbox/messages/2WL45YuHOLATvC3GspEu0oSioux.json
@@ -12,6 +12,7 @@
       "messageReference": "d1cc6082-729e-4e31-8842-ac3279d3f72d",
       "messageStatus": "failed",
       "messageStatusDescription": "Failed reason: NHS number not found",
+      "messageFailureReasonCode": "MFR_PDSV_0004",
       "channels": [
         {
           "type": "nhsapp",
@@ -20,6 +21,7 @@
           "cascadeOrder": 1,
           "channelStatus": "failed",
           "channelStatusDescription": "Failed reason: NHS number not found",
+          "channelFailureReasonCode": "CFR_PDSV_0004",
           "timestamps": {
             "created": "2023-10-09T10:31:59Z",
             "enriched": "2023-10-09T10:31:59Z",

diff --git a/sandbox/messages/2WL4JtCiOe7l2TT4szwPjNJah3z.json b/sandbox/messages/2WL4JtCiOe7l2TT4szwPjNJah3z.json
@@ -12,6 +12,7 @@
       "messageReference": "e21cd9c0-75af-4596-9e9a-57fa7581fe59",
       "messageStatus": "failed",
       "messageStatusDescription": "Failed reason: The provider could not deliver the message. This can happen when the recipient’s phone is off, has no signal, or their text message inbox is full. You can try to send the message again. You’ll still be charged for text messages to phones that are not accepting messages.",
+      "messageFailureReasonCode": "MFR_SUPE_0007",
       "channels": [
         {
           "type": "sms",
@@ -20,6 +21,7 @@
           "cascadeOrder": 1,
           "channelStatus": "failed",
           "channelStatusDescription": "Failed reason: The provider could not deliver the message. This can happen when the recipient’s phone is off, has no signal, or their text message inbox is full. You can try to send the message again. You’ll still be charged for text messages to phones that are not accepting messages.",
+          "channelFailureReasonCode": "CFR_SUPE_0007",
           "timestamps": {
             "created": "2023-10-09T10:31:59Z",
             "enriched": "2023-10-09T10:31:59Z",

diff --git a/sandbox/messages/2WL4MOuSeCTODDAScFG7KIq9a5r.json b/sandbox/messages/2WL4MOuSeCTODDAScFG7KIq9a5r.json
@@ -12,6 +12,7 @@
       "messageReference": "b9603694-5542-4043-b905-1e570b26d4c2",
       "messageStatus": "failed",
       "messageStatusDescription": "Failed reason: We had an unexpected error while sending the letter to our printing provider.",
+      "messageFailureReasonCode": "MFR_SUPE_0007",
       "channels": [
         {
           "type": "letter",
@@ -20,6 +21,7 @@
           "cascadeOrder": 1,
           "channelStatus": "failed",
           "channelStatusDescription": "Failed reason: We had an unexpected error while sending the letter to our printing provider.",
+          "channelFailureReasonCode": "CFR_SUPE_0007",
           "timestamps": {
             "created": "2023-10-09T10:31:59Z",
             "enriched": "2023-10-09T10:31:59Z",

diff --git a/sandbox/messages/2WL4QcKGjNHvHFQeKgYbapZJGHK.json b/sandbox/messages/2WL4QcKGjNHvHFQeKgYbapZJGHK.json
@@ -12,6 +12,7 @@
       "messageReference": "4fbc5f73-0f7c-4304-b848-5c6ccb781c84",
       "messageStatus": "failed",
       "messageStatusDescription": "Failed reason: Patient does not exist in PDS",
+      "messageFailureReasonCode": "MFR_PDSV_0006",
       "timestamps": {
         "created": "2023-10-09T10:31:37Z",
         "enriched": "2023-10-09T10:31:40Z",

diff --git a/sandbox/messages/2WL4W9RgbuLLByXdR77H8vjKSDd.json b/sandbox/messages/2WL4W9RgbuLLByXdR77H8vjKSDd.json
@@ -12,6 +12,7 @@
       "messageReference": "0397b134-e30d-4fb1-9060-0d204b0ac340",
       "messageStatus": "failed",
       "messageStatusDescription": "Failed reason: The provider could not deliver the message. This can happen when the recipient’s inbox is full or their anti-spam filter rejects your email. Check your content does not look like spam before you try to send the message again.",
+      "messageFailureReasonCode": "MFR_SUPE_0007",
       "channels": [
         {
           "type": "email",
@@ -20,6 +21,7 @@
           "cascadeOrder": 1,
           "channelStatus": "failed",
           "channelStatusDescription": "Failed reason: The provider could not deliver the message. This can happen when the recipient’s inbox is full or their anti-spam filter rejects your email. Check your content does not look like spam before you try to send the message again.",
+          "channelFailureReasonCode": "CFR_SUPE_0007",
           "timestamps": {
             "created": "2023-10-09T10:31:59Z",
             "enriched": "2023-10-09T10:31:59Z",

diff --git a/sandbox/messages/2WL4cPfBRuPKa44JxhyXYf2kr1E.json b/sandbox/messages/2WL4cPfBRuPKa44JxhyXYf2kr1E.json
@@ -12,6 +12,7 @@
       "messageReference": "d85be1f0-1593-41b0-94d2-beae6ee7dcc0",
       "messageStatus": "failed",
       "messageStatusDescription": "Failed reason: patient record invalidated",
+      "messageFailureReasonCode": "MFR_PDSV_0008",
       "timestamps": {
         "created": "2023-10-09T10:31:37Z",
         "enriched": "2023-10-09T10:31:45Z",

diff --git a/sandbox/messages/2WL4ibGoigirgbH4yQwqbPaJXyQ.json b/sandbox/messages/2WL4ibGoigirgbH4yQwqbPaJXyQ.json
@@ -12,6 +12,7 @@
       "messageReference": "2f2e071c-9fba-4dde-bf8d-8dd0c8060300",
       "messageStatus": "failed",
       "messageStatusDescription": "Failed reason: Patient is formally dead",
+      "messageFailureReasonCode": "MFR_PDSV_0112",
       "timestamps": {
         "created": "2023-10-09T10:31:37Z",
         "enriched": "2023-10-09T10:31:59Z",

diff --git a/sandbox/messages/2WL4khXn32dOOj4bB4bi8Tkllrq.json b/sandbox/messages/2WL4khXn32dOOj4bB4bi8Tkllrq.json
@@ -12,6 +12,7 @@
       "messageReference": "68cc8e05-c404-405a-a41d-92cdb8afd9e3",
       "messageStatus": "failed",
       "messageStatusDescription": "Failed reason: Patient is informally dead",
+      "messageFailureReasonCode": "MFR_PDSV_0111",
       "timestamps": {
         "created": "2023-10-09T10:31:37Z",
         "enriched": "2023-10-09T10:31:59Z",

diff --git a/sandbox/messages/2WL4mvx6eBva8dcIK60VEGIfcgZ.json b/sandbox/messages/2WL4mvx6eBva8dcIK60VEGIfcgZ.json
@@ -12,6 +12,7 @@
       "messageReference": "1791d23b-6f5d-4153-ab45-637bd7711d41",
       "messageStatus": "failed",
       "messageStatusDescription": "Failed reason: Patient has exit code",
+      "messageFailureReasonCode": "MFR_PDSV_0110",
       "timestamps": {
         "created": "2023-10-09T10:31:37Z",
         "enriched": "2023-10-09T10:31:59Z",

diff --git a/sandbox/messages/2WL4pcpmKxYYblm3PSKVEqcmEPX.json b/sandbox/messages/2WL4pcpmKxYYblm3PSKVEqcmEPX.json
@@ -12,6 +12,7 @@
       "messageReference": "2c98d875-3843-4919-9c79-2034e957e251",
       "messageStatus": "failed",
       "messageStatusDescription": "Failed reason: Name response is invalid: Contact detail is malformed",
+      "messageFailureReasonCode": "MFR_PDSV_0001",
       "timestamps": {
         "created": "2023-10-09T10:31:37Z",
         "enriched": "2023-10-09T10:31:59Z",

diff --git a/sandbox/messages/2WL4vHFZzInmaYwq6HRNDqTX8dH.json b/sandbox/messages/2WL4vHFZzInmaYwq6HRNDqTX8dH.json
@@ -12,6 +12,7 @@
       "messageReference": "d1cc6082-729e-4e31-8842-ac3279d3f72d",
       "messageStatus": "failed",
       "messageStatusDescription": "Failed reason: Contact detail is missing",
+      "messageFailureReasonCode": "MFR_PDSV_0002",
       "channels": [
         {
           "type": "nhsapp",
@@ -20,6 +21,7 @@
           "cascadeOrder": 1,
           "channelStatus": "failed",
           "channelStatusDescription": "Failed reason: Contact detail is missing",
+          "channelFailureReasonCode": "CFR_PDSV_0002",
           "timestamps": {
             "created": "2023-10-09T10:31:59Z",
             "enriched": "2023-10-09T10:31:59Z",

diff --git a/sandbox/messages/2WL4xcWKvz4F32g0htBEl8DINzn.json b/sandbox/messages/2WL4xcWKvz4F32g0htBEl8DINzn.json
@@ -12,6 +12,7 @@
       "messageReference": "0b88296d-b7e3-4697-be86-7424444a205c",
       "messageStatus": "failed",
       "messageStatusDescription": "Failed reason: Contact detail is missing",
+      "messageFailureReasonCode": "MFR_PDSV_0002",
       "channels": [
         {
           "type": "email",
@@ -20,6 +21,7 @@
           "cascadeOrder": 1,
           "channelStatus": "failed",
           "channelStatusDescription": "Failed reason: Contact detail is missing",
+          "channelFailureReasonCode": "CFR_PDSV_0002",
           "timestamps": {
             "created": "2023-10-09T10:31:59Z",
             "failed": "2023-10-09T10:52:12Z"

diff --git a/sandbox/messages/2WL50w41YaZXcyFCNT346LY8rlz.json b/sandbox/messages/2WL50w41YaZXcyFCNT346LY8rlz.json
@@ -12,6 +12,7 @@
       "messageReference": "7b2be2cf-7e59-4b15-b199-fd4ba0cb9f19",
       "messageStatus": "failed",
       "messageStatusDescription": "Failed reason: Contact detail is missing",
+      "messageFailureReasonCode": "MFR_PDSV_0002",
       "channels": [
         {
           "type": "sms",
@@ -20,6 +21,7 @@
           "cascadeOrder": 1,
           "channelStatus": "failed",
           "channelStatusDescription": "Failed reason: Contact detail is missing",
+          "channelFailureReasonCode": "CFR_PDSV_0002",
           "timestamps": {
             "created": "2023-10-09T10:31:59Z",
             "enriched": "2023-10-09T10:31:59Z",

diff --git a/sandbox/messages/2WL54x0XQjCbWeE5lN0DKQZcokU.json b/sandbox/messages/2WL54x0XQjCbWeE5lN0DKQZcokU.json
@@ -12,6 +12,7 @@
       "messageReference": "1226417c-f683-4d68-afe8-2d52321a6b70",
       "messageStatus": "failed",
       "messageStatusDescription": "Failed reason: Contact detail is missing",
+      "messageFailureReasonCode": "MFR_PDSV_0002",
       "channels": [
         {
           "type": "letter",
@@ -20,6 +21,7 @@
           "cascadeOrder": 1,
           "channelStatus": "failed",
           "channelStatusDescription": "Failed reason: Contact detail is missing",
+          "channelFailureReasonCode": "CFR_PDSV_0002",
           "timestamps": {
             "created": "2023-10-09T10:31:59Z",
             "enriched": "2023-10-09T10:31:59Z",

diff --git a/sandbox/messages/2WL5eDefrbW31uw1il84WdF8ndH.json b/sandbox/messages/2WL5eDefrbW31uw1il84WdF8ndH.json
@@ -19,6 +19,7 @@
           "cascadeOrder": 1,
           "channelStatus": "failed",
           "channelStatusDescription": "Failed reason: NHS number not found",
+          "channelFailureReasonCode": "CFR_PDSV_0004",
           "timestamps": {
             "created": "2023-10-09T10:31:59Z",
             "enriched": "2023-10-09T10:39:37Z",

diff --git a/sandbox/messages/2WL5eYSWGzCHlGmzNxuqVusPxDg.json b/sandbox/messages/2WL5eYSWGzCHlGmzNxuqVusPxDg.json
@@ -19,6 +19,7 @@
           "cascadeOrder": 1,
           "channelStatus": "failed",
           "channelStatusDescription": "Failed reason: NHS number not found",
+          "channelFailureReasonCode": "CFR_PDSV_0004",
           "timestamps": {
             "created": "2023-10-09T10:31:59Z",
             "enriched": "2023-10-09T10:39:37Z",
@@ -37,6 +38,7 @@
           "cascadeOrder": 2,
           "channelStatus": "failed",
           "channelStatusDescription": "Failed reason: The provider could not deliver the message. This can happen when the recipient’s inbox is full or their anti-spam filter rejects your email. Check your content does not look like spam before you try to send the message again.",
+          "channelFailureReasonCode": "CFR_SUPE_0007",
           "timestamps": {
             "created": "2023-10-09T10:31:59Z",
             "enriched": "2023-10-09T10:39:37Z",

diff --git a/sandbox/messages/2WL5f8j4XVxUPgd3OOqXVYvVFIW.json b/sandbox/messages/2WL5f8j4XVxUPgd3OOqXVYvVFIW.json
@@ -19,6 +19,7 @@
           "cascadeOrder": 1,
           "channelStatus": "failed",
           "channelStatusDescription": "Failed reason: NHS number not found",
+          "channelFailureReasonCode": "CFR_PDSV_0004",
           "timestamps": {
             "created": "2023-10-09T10:31:59Z",
             "enriched": "2023-10-09T10:39:37Z",
@@ -37,6 +38,7 @@
           "cascadeOrder": 2,
           "channelStatus": "failed",
           "channelStatusDescription": "Failed reason: The provider could not deliver the message. This can happen when the recipient’s inbox is full or their anti-spam filter rejects your email. Check your content does not look like spam before you try to send the message again.",
+          "channelFailureReasonCode": "CFR_SUPE_0007",
           "timestamps": {
             "created": "2023-10-09T10:31:59Z",
             "enriched": "2023-10-09T10:39:37Z",
@@ -55,6 +57,7 @@
           "cascadeOrder": 3,
           "channelStatus": "failed",
           "channelStatusDescription": "Failed reason: The provider could not deliver the message. This can happen when the recipient’s phone is off, has no signal, or their text message inbox is full. You can try to send the message again. You’ll still be charged for text messages to phones that are not accepting messages.",
+          "channelFailureReasonCode": "CFR_SUPE_0007",
           "timestamps": {
             "created": "2023-10-09T10:31:59Z",
             "enriched": "2023-10-09T10:39:37Z",

diff --git a/sandbox/messages/2bBBpsiMl2rnQt99qm6JLZ6w1vq.json b/sandbox/messages/2bBBpsiMl2rnQt99qm6JLZ6w1vq.json
@@ -12,6 +12,7 @@
       "messageReference": "1226417c-f683-4d68-afe8-2d52321a6b70",
       "messageStatus": "failed",
       "messageStatusDescription": "Failed reason: Contact detail is missing",
+      "messageFailureReasonCode": "MFR_PDSV_0002",
       "channels": [
         {
           "type": "sms",
@@ -20,6 +21,7 @@
           "cascadeOrder": 1,
           "channelStatus": "failed",
           "channelStatusDescription": "Failed reason: Contact detail is missing",
+          "channelFailureReasonCode": "CFR_PDSV_0002",
           "timestamps": {
             "created": "2023-10-09T10:31:59Z",
             "failed": "2023-10-09T10:52:12Z"