Skip to main content

Sending a message with NHS Notify MESH

Learn how to send one or multiple messages using NHS Notify MESH.

Page contents

What you need to know

To send messages to your recipients with NHS Notify MESH, you make a request from your MESH mailbox to NHS Notify's mailbox.

Depending on how you choose to access MESH, you may need to understand how to:

When NHS Notify has processed your request, your messages will be sent to your recipients according to your routing plan(s). 

How to create your request

1. Add your request headers

You must add the following MESH header fields so NHS Notify can identify your request.

MESH header field Mandatory Type Description Example
mex-subject Yes UUID The ID created by NHS Notify for the routing plan that the messages in the request uses. You'll be given your routing plan IDs during onboarding. 33ead2f4-da0a-11ed-afa1-0242ac120002
mex-localid Yes String The ID that you create for a batch of messages. yourInternalReference_01
mex-workflowid Yes String The Workflow ID used to send a request. NHS_NOTIFY_SEND_REQUEST

 

2. Add your recipients details

To tell NHS Notify who you want to message, you must include a comma-separated values (CSV) file in your request with their details. You only need to provide your recipients' NHS numbers. NHS Notify will find their contact details using the Personal Demographics Service (PDS).

The CSV must be smaller than 2GB and cannot contain more than 6 million messages.

Add the following columns in your CSV.

Column name Mandatory Type Description Example
messageReference Yes String The ID of an individual request you created within a batch of requests.

yourInternal

Reference

ToThisRecipient_01
nhsNumber Yes String NHS number of the recipient. 9999999123

personalisation_

{parameterName}

 No String The personalisation parameters used in the message templates that will be sent to your recipients. If you have multiple personalisation parameters, add a new column for each in the following format: personalisation_{parameterName}

personalisation_

AppointmentDate
originator_odsCode No (disabled by default) String ODS code used to tell recipients who your NHS App messages are from. Learn more about NHS app sender names (opens in a new tab).

B82016

Providing your own recipient contact details

If you need to use contact details that are not from PDS, you must make a formal request to NHS Notify. Overriding contact details is only granted to specific use-cases that provide compelling data to our onboarding team who will consult with legal and clinical teams for approval. Requests that use overridden contact details without NHS Notify's approval will be automatically rejected.

Add the following columns to your CSV to use overridden contact details:

Column name Mandatory Type Description Example
recipient_contactDetails_email No (disabled by default) String The recipient's email address.

joe.bloggs

@example.com
recipient_contactDetails_sms No (disabled by default) String The recipients mobile phone number. 07700900123
recipient_contactDetails_address_lines1 No (disabled by default) String First line of the recipient's address. NHS England
recipient_contactDetails_address_lines2 No (disabled by default) String Second line of the recipient's address. 6th Floor
recipient_contactDetails_address_lines3 No (disabled by default) String Third line of the recipient's address. 7 and 8 Wellington Place
recipient_contactDetails_address_lines4 No (disabled by default) String Fourth line of the recipient's address. Leeds
recipient_contactDetails_address_lines5 No (disabled by default) String Fifth line of the recipient's address. West Yorkshire
recipient_contactDetails_address_postcode No (disabled by default) String The recipient's postcode. LS1 4AP

 

Sending your request

Once you've created your request, you can send it to one of NHS Notify's MESH mailboxes. NHS Notify polls its MESH mailboxes every 5 minutes.

If you're sending a request for the first time, you should send your request to the integration mailbox for integration testing.

After you have completed integration testing and are live with NHS Notify, you can send your request to the production mailbox.

Environment Mesh mailbox ID
Integration X26OT282
Production C4L8EHC001

NHS Notify confirms it has received your request

After you send your request, NHS Notify will confirm it has received your request by sending a confirmation message to your MESH mailbox.

The message will include MESH header fields and a JSON file with additional data about your request.

 

MESH header fields

The following table shows you the MESH header fields you'll receive in your confirmation message from NHS Notify.

Mesh header field Mandatory Type Description Example
mex-subject Yes String

Shows if your request was successful or not using a HTTP status code. 

 Find out what HTTP status codes you can receive.

 404
mex-localid Yes String

The ID of the request you made to NHS Notify (the mex-localid header of your request).

 yourInternalReference_01
mex-workflowid Yes String

The name of the workflow used for the request.

This will always be NHS_NOTIFY_SEND_REQUEST_ACK.

NHS_NOTIFY_SEND_

REQUEST_ACK

 

Additional data (JSON file)

The following table shows you what strings to expect in the JSON file attached to the confirmation message.

Column name Mandatory Type Description Example
meshMessageId Yes String The message ID created by MESH of the original request message. 20200601122152994285_D59900
requestId No String A reference created by NHS Notify for your request (only appears if your request is successful). 2OYhPQ3x37GYhRYTF0nwwyl4OXQ
message No String Tells you why your request was not successful (only appears if your request was not successful).  Routing plan does not exist for sendingGroupId \"abcd-efgh\"

 

Next page

Get reports on how your messages perform

Find out how your messages perform using NHS Notify MESH

Last edited: 17 December 2024 11:15 am