diff --git a/specification/callbacks/returned_mail.yaml b/specification/callbacks/returned_mail.yaml new file mode 100644 index 000000000..b0218207e --- /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 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 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..a95cf3ff2 --- /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 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'