CCM-20500: Return mail API documentation

specification/callbacks/returned_mail.yaml

@@ -0,0 +1,43 @@
+summary: Returned mail
+description: |-
+  The returned mail callback sends a POST request to your service when NHS Notify is informed that a letter has been returned.
+
+  If you're onboarding with NHS Notify and need to use the returned mail callback, contact the onboarding team to tell them you want to subscribe to returned mail events.
+
+  If you're live with NHS Notify and need to use the returned mail callback, [raise a Service Now ticket](https://nhsdigitallive.service-now.com/csm).
+
+  ### About returned mail
+
+  When NHS Notify receives information that a letter has been returned, it sends a callback to your service with the details of the return.
+
+  The callback includes the return reason code and text, the message it relates to, and the time the callback event was processed.
+
+  Callbacks can arrive more than once or out of order. Use `meta.idempotencyKey` to identify duplicate events. See the callback guidance above for retries and rate limiting.
+
+  ### Authentication
+
+  This callback uses mutual TLS (mTLS) for authentication instead of HMAC signatures or API keys. NHS Notify presents a client certificate when connecting to your endpoint. Your service must validate the inbound client certificate against the NHS Notify CA to authenticate the request.
+operationId: post-v1-returned-mail-callbacks
+security: []
+requestBody:
+  content:
+    application/vnd.api+json:
+      schema:
+        type: object
+        required:
+          - data
+        properties:
+          data:
+            type: array
+            minItems: 1
+            items:
+              $ref: ../schemas/components/ReturnedMailCallback.yaml
+responses:
+    '202':
+        description: Accepted
+    '401':
+        description: Unauthorized
+    '403':
+        description: Forbidden
+    '429':
+        $ref: ../responses/4xx/callbacks/429_TooManyRequests_Callbacks.yaml

specification/communications-manager.yaml

@@ -58,3 +58,7 @@ paths:
     post:
       $ref: callbacks/recipient_response.yaml
       tags: ['Callbacks']
+  /{client-provided-returned-mail-URI}:
+    post:
+      $ref: callbacks/returned_mail.yaml
+      tags: ['Callbacks']

specification/documentation/APIDescription.md

@@ -241,6 +241,10 @@ If you are using the newer callback mechanism, it is also possible to limit the
 
 Speak to our onboarding team if you need to set a rate limit or extend the retry period.
 
+### Returned mail
+
+If you subscribe to returned mail callbacks, NHS Notify will send you a callback when it receives a returned mail event for a letter sent on your behalf. See [the returned mail callback](#post-/-client-provided-returned-mail-URI-) for the request format and response codes.
+
 ## Two-way messaging
 
 **This feature is currently under development and is not yet ready to use.**

specification/schemas/components/ReturnedMailCallback.yaml

@@ -0,0 +1,65 @@
+type: object
+title: CallbackRequest
+required:
+  - type
+  - attributes
+  - links
+  - meta
+properties:
+  type:
+    type: string
+    enum:
+      - ReturnedMail
+    example: ReturnedMail
+  attributes:
+    type: object
+    required:
+      - messageId
+      - messageReference
+      - channel
+      - reason
+      - reasonText
+      - timestamp
+    properties:
+      messageId:
+        $ref: ../types/KSUID.yaml
+      messageReference:
+        $ref: ../../snippets/MessageReferenceSnippet.yaml
+      channel:
+        type: string
+        description: The channel used for the returned message.
+        enum:
+          - letter
+        example: letter
+      reason:
+        type: string
+        description: Code indicating why the letter was returned.
+        example: UNDELIVERABLE
+      reasonText:
+        type: string
+        description: Text describing why the letter was returned.
+        example: 'Unable to deliver: address not found'
+      timestamp:
+        type: string
+        description: Date and time NHS Notify processed this callback event.
+        format: date-time
+        example: '2026-07-01T10:00:00.000Z'
+  links:
+    type: object
+    required:
+      - message
+    properties:
+      message:
+        type: string
+        description: URL to retrieve the related message.
+        format: uri
+        example: 'https://api.service.nhs.uk/comms/v1/messages/2WL3qFTEFM0qMY8xjRbt1LIKCzM'
+  meta:
+    type: object
+    required:
+      - idempotencyKey
+    properties:
+      idempotencyKey:
+        type: string
+        description: Value to use to identify duplicate callback events, even if their timestamps differ.
+        example: '2515ae6b3a08339fba3534f3b17cd57cd573c57d25b25b9aae08e42dc9f0a445'