--- title: "Get the status of a message" method: GET path: "/v1/messages/{messageId}" --- # Get the status of a message `GET /v1/messages/{messageId}` ## Overview Use this endpoint to fetch the status of a single message sent by your account. ### Channels The [NHS Notify Service](https://digital.nhs.uk/services/nhs-notify) supports multiple channels for delivering a message. These channels are: * sms * email * letter * NHS app The channels used to send your message are configured within the routing plan. These routing plans are configured during your [onboarding process](#overview--onboarding). The channels configured in your routing plan at the time of sending are returned as part of the message status response. The channels are returned in the order that sending will be attempted. 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, only returned if sending is retried one or more times. * `timestamps` - timestamps of key events * `routingPlan` - the routing plan that was used to generate the channel Each channel can have one of the following statuses: * `created` - the channel has been created * `skipped` - the channel has been skipped * `sending` - the channel is in the process of sending the message * `delivered` - the channel has delivered the message * `failed` - the channel has failed to deliver the message If your routing plan supports conditional overrides, then in certain situations the routing plan referenced by a channel may be different from the one you initially requested. If this occurs then the `routingPlan.type` field will be set to the value `override`, plus the `id` and `version` fields will reflect the override that was used. The following CURL request example highlights this interaction and can be replicated using message id `2bBBpsiMl2rnQt99qm6JLZ6w1vq`: ``` curl -X GET 'https://sandbox.api.service.nhs.uk/comms/v1/messages/2bBBpsiMl2rnQt99qm6JLZ6w1vq' \ --header 'Accept: application/vnd.api+json' ``` ### 3rd Party Querying This system queries 3rd party integrations during the sending process. If this occurs, the `metadata` field will be populated with information about the queries made, including: * `queriedAt` - the date and time that the query occurred at * `version` - a version of the document returned in the query, if supported by the 3rd party * `labels` - the channels that the response affected * `source` - the 3rd party system the query was made to The 3rd party systems being queried are: * `pds` - [Personal Demographics Service](https://digital.nhs.uk/services/personal-demographics-service) ### Personalisation & Contact details Personalisation and contact details are not returned within the messages. This is to ensure that Personally Identifiable Information cannot be extracted from the system. ### Sandbox When sending this request on sandbox you can use one of these 5 message references: * single message status of delivered - `2WL3qFTEFM0qMY8xjRbt1LIKCzM` * single message delivered using multiple channels - `2WL5eYSWGzCHlGmzNxuqVusPxDg` * single message status of sending - `2WL4GEeFVxXG9S57nRlefBwwKxp` * single message failed as patient has an exit code - `2WL4mvx6eBva8dcIK60VEGIfcgZ` * single message routing plan overriden - `2bBBpsiMl2rnQt99qm6JLZ6w1vq` Here's an example curl command using one of the above message references: ``` curl -X GET 'https://sandbox.api.service.nhs.uk/comms/v1/messages/2WL3qFTEFM0qMY8xjRbt1LIKCzM' \ --header 'Accept: application/vnd.api+json' ``` ## Parameters - `#/paths/~1v1~1messages/post/parameters/0` — unresolved $ref - `#/paths/~1v1~1messages/post/parameters/1` — unresolved $ref ## Response `200` The message has been found and its details are contained within the response body. - object - `data` object - `type` Type, required — unresolved $ref - `id` Schema, required — unresolved $ref - `attributes` object, required - `messageReference` MessageReference, required — unresolved $ref - `messageStatus` MessageStatus, required — unresolved $ref - `messageStatusDescription` string — If there is extra information associated with the status of this message, it is provided here. - `messageFailureReasonCode` string — If there is a failed reason code associated with this message, it is provided here. - `channels` object[] — This array contains the channels that attempts to send your message will use, ordered as they will be attempted. This array will remain empty (or not present) in the response until your message has gone through enrichment. - `type` Type, required — unresolved $ref - `retryCount` RetryCount — unresolved $ref - `cascadeType` CascadeType, required — unresolved $ref - `cascadeOrder` CascadeOrder, required — unresolved $ref - `channelStatus` ChannelStatus, required — unresolved $ref - `channelStatusDescription` string — If there is extra information associated with the status of this channel, it is provided here. - `channelFailureReasonCode` string — If there is a failed reason code associated with this channel, it is provided here. - `supplierStatus` SupplierStatus — unresolved $ref - `timestamps` object, required - `created` string, date-time, required — The date and time that this channel was created at. - `delivered` string, date-time — The date and time that this channel was successfully delivered. - `failed` string, date-time — The date and time that this channel failed to be delivered. - `routingPlan` object, required — The routing plan that this channel was generated from. - `id` string, uuid, required — The identifier for the routing plan. - `version` string — This identifies the specific version of the routing plan. - `type` 'original' | 'override', required — Identifies if this is the original routing plan that was requested, or if a conditional override has been used. - `metadata` Metadata — unresolved $ref - `timestamps` object, required - `created` string, date-time, required — The date and time that your message was created at. - `enriched` string, date-time — The date and time when we enriched the recipients details from the [Personal Demographics Service](https://digital.nhs.uk/services/personal-demographics-service). This is the business effective date that should be used when reviewing the patients details within PDS. - `delivered` string, date-time — The date and time that this message was successfully delivered. - `failed` string, date-time — The date and time that this message failed to be delivered. - `metadata` object[] — This array includes a list of all metadata lookups done for this message within the system. Currently only PDS is used for lookups. - `version` string — This is the version of the document that was received from this source. - `queriedAt` string, date-time, required — This is the date and time the query was made (business effective date). - `labels` string[] — This is an array of labels indicating what this lookup affects. This may include the channels that were affected. - `source` 'pds', required — This is the service that was queried. - `routingPlan` RoutingPlan, required — unresolved $ref - `relationships` object — This object contains information about other objects related to this message. - `messageBatch` object — If your message was sent as part of a batch, then this property will be present. - `data` object - `type` Type, required — unresolved $ref - `id` Schema, required — unresolved $ref - `links` Links, required — unresolved $ref ## Other responses - `401` — unresolved $ref - `403` — unresolved $ref - `404` — The message has not been found, check the message identifier passed in the URL for any errors and then try again. ### Sandbox On sandbox it is possible to simulate a 404 not found error using the `Prefer` header with a value of `code=404`. Here is an example curl request to trigger a `404`: ``` curl -X GET \ --header "Accept: */*" \ --header "Content-type: application/vnd.api+json" \ --header "Prefer: code=404" \ https://sandbox.api.service.nhs.uk/comms ``` - `405` — unresolved $ref - `406` — unresolved $ref - `408` — unresolved $ref - `429` — unresolved $ref - `500` — unresolved $ref - `503` — unresolved $ref - `504` — unresolved $ref --- [API](https://skmtc.dev/nhs/apis/communications-manager-api.md) · [All operations](https://skmtc.dev/nhs/apis/communications-manager-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nhs/communications-manager-api/revisions/286b22343680/schema)