NHSDigital · Ian-Hodges · Aug 6, 2025 · Jul 9, 2025 · Jul 10, 2025 · Jul 10, 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/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"

diff --git a/specification/documentation/GetMessage.md b/specification/documentation/GetMessage.md
@@ -22,6 +22,7 @@ Key values that are returned for each of these channels are:
 * `type` - the channel type
 * `channelStatus` - the status of that channel
 * `channelStatusDescription` - the channel status description
+* `channelFailureReasonCode` - the channel failed reason code
 * `supplierStatus` - the status provided by the supplier for this channel
 * `retryCount` - the number of times we have attempted delivery
 * `timestamps` - timestamps of key events

diff --git a/specification/schemas/components/MessageStatus.yaml b/specification/schemas/components/MessageStatus.yaml
@@ -18,7 +18,11 @@ properties:
       messageStatusDescription:
         type: string
         description: If there is extra information associated with the status of this message, it is provided here.
-        example: " "
+        example: "Failed reason: Contact detail is missing"
+      messageFailureReasonCode:
+        type: string
+        description: If there is a failed reason code associated with this message, it is provided here.
+        example: "MFR_PDSV_0002"
       channels:
         type: array
         minItems: 0

diff --git a/specification/schemas/components/SupplierStatus.yaml b/specification/schemas/components/SupplierStatus.yaml
@@ -30,7 +30,11 @@ properties:
       channelStatusDescription:
         type: string
         description: If there is extra information associated with the status of this channel, it is provided here.
-        example: " "
+        example: "Failed reason: Contact detail is missing"
+      channelFailureReasonCode:
+        type: string
+        description: If there is a failed reason code associated with this channel, it is provided here.
+        example: "CFR_PDSV_0002"
       supplierStatus:
         $ref: ../enums/SupplierStatusEnum.yaml
       timestamp:

diff --git a/specification/schemas/responses/MessageResponse.yaml b/specification/schemas/responses/MessageResponse.yaml
@@ -25,7 +25,11 @@ properties:
           messageStatusDescription:
             type: string
             description: If there is extra information associated with the status of this message, it is provided here.
-            example: ""
+            example: "Failed reason: Contact detail is missing"
+          messageFailureReasonCode:
+            type: string
+            description: If there is a failed reason code associated with this message, it is provided here.
+            example: "MFR_PDSV_0002"
           channels:
             type: array
             description: |-
@@ -54,7 +58,11 @@ properties:
                 channelStatusDescription:
                   type: string
                   description: If there is extra information associated with the status of this channel, it is provided here.
-                  example: ""
+                  example: "Failed reason: Contact detail is missing"
+                channelFailureReasonCode:
+                  type: string
+                  description: If there is a failed reason code associated with this channel, it is provided here.
+                  example: "CFR_PDSV_0002"
                 supplierStatus:
                   description: |-
                     The current status of this message within the channel at the time this response was generated.