CCM-17052: Add new DigitalLetterUnsuccessful event

Author: tdroza-nhs

docs/collections/_diagrams/c4code-nhsapp-status-handler.md

@@ -11,10 +11,14 @@ architecture-beta
     service lambda(logos:aws-lambda)[App Status Handler] in AppStatusHandler
     service sqs(logos:aws-sqs)[App Status Queue] in AppStatusHandler
     service ddb(aws:arch-amazon-dynamodb)[Items With TTL] in AppStatusHandler
-    service docReadEvent(aws:res-amazon-eventbridge-event)[DigitalLetterRead Event]
+    service letterReadEvent(aws:res-amazon-eventbridge-event)[DigitalLetterRead Event]
+    service letterUnsuccessfulEvent(aws:res-amazon-eventbridge-event)[DigitalLetterUnsuccessful Event]
+    junction j1
 
     optedOutEvent:R --> L:sqs
     sqs:R --> L:lambda
     lambda:B --> T:ddb
-    lambda:R --> L:docReadEvent
+    lambda:R -- L:j1
+    j1:R --> L:letterReadEvent
+    j1:B --> L:letterUnsuccessfulEvent
 ```

docs/collections/_events/queue-digital-letter-unsuccessful.md

@@ -0,0 +1,10 @@
+---
+title: queue-digital-letter-unsuccessful
+type: uk.nhs.notify.digital.letters.queue.digital.letter.unsuccessful.v1
+nice_name: DigitalLetterUnsuccessful
+service: Queue Services
+schema_envelope:  https://notify.nhs.uk/cloudevents/schemas/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.queue.digital.letter.unsuccessful.v1.schema.json
+schema_data: https://notify.nhs.uk/cloudevents/schemas/digital-letters/2025-10-draft/data/digital-letters-queue-digital-letter-unsuccessful-data.schema.json
+---
+
+This indicates that a digital letter has failed to send to the NHS App.

src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-queue-digital-letter-unsuccessful-data.schema.yaml

@@ -0,0 +1,19 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+title: DigitalLetterUnsuccessful Data
+description: Data payload of the DigitalLetterUnsuccessful event
+type: object
+additionalProperties: false
+properties:
+  messageReference:
+    $ref: ../defs/requests.schema.yaml#/properties/messageReference
+  senderId:
+    $ref: ../defs/requests.schema.yaml#/properties/senderId
+  failureCode:
+    $ref: ../defs/core.schema.yaml#/properties/failureCode
+  failureReason:
+    $ref: ../defs/core.schema.yaml#/properties/failureReason
+required:
+  - messageReference
+  - senderId
+  - failureCode
+  - failureReason

src/cloudevents/domains/digital-letters/2025-10-draft/defs/core.schema.yaml

@@ -15,9 +15,12 @@ properties:
     type: string
     description: "A code representing the reason for failure"
     examples:
-      - "CM_NOT_ALLOWED"
-      - "CM_NO_SUCH_ROUTING_PLAN"
-      - "CM_DUPLICATE_REQUEST"
+      - "CFR_SUPE_0001"
+  failureReason:
+    type: string
+    description: "A human readable desription of the reason for failure"
+    examples:
+      - "Failed reason: Not registered with NHS App"
   time:
     title: "Event Time"
     description: "Timestamp when the event occurred (RFC 3339)."

src/cloudevents/domains/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.queue.digital.letter.unsuccessful.v1.schema.yaml

@@ -0,0 +1,23 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+title: DigitalLetterUnsuccessful
+type: object
+allOf:
+  - $ref: ../digital-letters-queue-profile.schema.yaml
+properties:
+  type:
+    type: string
+    const: uk.nhs.notify.digital.letters.queue.digital.letter.unsuccessful.v1
+    description: Concrete versioned event type string for this event (.vN suffix).
+  source:
+    type: string
+    pattern: ^/nhs/england/notify/(production|staging|development|uat)/(primary|secondary|dev-[0-9]+)/digitalletters/queue
+    description: Event source for digital letters.
+
+  dataschema:
+    type: string
+    const: ../data/digital-letters-queue-digital-letter-unsuccessful-data.schema.yaml
+    description: Canonical URI of the event's data schema.
+    examples:
+      - digital-letters-queue-digital-letter-unsuccessful-data.schema.yaml
+  data:
+    $ref: ../data/digital-letters-queue-digital-letter-unsuccessful-data.schema.yaml