From 5747fcc98b4a6f10daf606b640c108ae1f9188a7 Mon Sep 17 00:00:00 2001 From: Rhys Cox Date: Tue, 27 Oct 2026 11:08:11 +0000 Subject: [PATCH 1/2] CCM-20500: Return mail API documentation --- specification/callbacks/returned_mail.yaml | 43 ++++++++++++ specification/communications-manager.yaml | 4 ++ specification/documentation/APIDescription.md | 4 ++ .../components/ReturnedMailCallback.yaml | 65 +++++++++++++++++++ 4 files changed, 116 insertions(+) create mode 100644 specification/callbacks/returned_mail.yaml create mode 100644 specification/schemas/components/ReturnedMailCallback.yaml diff --git a/specification/callbacks/returned_mail.yaml b/specification/callbacks/returned_mail.yaml new file mode 100644 index 000000000..1558ba714 --- /dev/null +++ b/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 notified that a letter is 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 is notified that a letter is 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 diff --git a/specification/communications-manager.yaml b/specification/communications-manager.yaml index aa492d0ad..a3cb19ef2 100644 --- a/specification/communications-manager.yaml +++ b/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'] diff --git a/specification/documentation/APIDescription.md b/specification/documentation/APIDescription.md index d36639bf4..25678ef52 100644 --- a/specification/documentation/APIDescription.md +++ b/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.** diff --git a/specification/schemas/components/ReturnedMailCallback.yaml b/specification/schemas/components/ReturnedMailCallback.yaml new file mode 100644 index 000000000..6aac655be --- /dev/null +++ b/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 of the returned mail 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' From c4a105f1968c278b69c17720c85e849e77d680e0 Mon Sep 17 00:00:00 2001 From: Rhys Cox Date: Tue, 27 Oct 2026 12:09:10 +0000 Subject: [PATCH 2/2] CCM-20500: PR feedback --- specification/callbacks/returned_mail.yaml | 4 ++-- specification/schemas/components/ReturnedMailCallback.yaml | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/callbacks/returned_mail.yaml b/specification/callbacks/returned_mail.yaml index 1558ba714..b0218207e 100644 --- a/specification/callbacks/returned_mail.yaml +++ b/specification/callbacks/returned_mail.yaml @@ -1,6 +1,6 @@ summary: Returned mail description: |- - The returned mail callback sends a POST request to your service when NHS Notify is notified that a letter is returned. + 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. @@ -8,7 +8,7 @@ description: |- ### About returned mail - When NHS Notify is notified that a letter is returned, it sends a callback to your service with the details of the return. + 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. diff --git a/specification/schemas/components/ReturnedMailCallback.yaml b/specification/schemas/components/ReturnedMailCallback.yaml index 6aac655be..a95cf3ff2 100644 --- a/specification/schemas/components/ReturnedMailCallback.yaml +++ b/specification/schemas/components/ReturnedMailCallback.yaml @@ -41,7 +41,7 @@ properties: example: 'Unable to deliver: address not found' timestamp: type: string - description: Date and time of the returned mail event. + description: Date and time NHS Notify processed this callback event. format: date-time example: '2026-07-01T10:00:00.000Z' links: