Sending a message with NHS Notify MESH
Learn how to send one or multiple messages using NHS Notify MESH.
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:
- send a message to a MESH mailbox with MESH API
- send and receive data with MESH Client
- send a file with MESH UI
When NHS Notify has processed your request, your messages will be sent to your recipients according to your routing plan.
We'll attempt to deliver the message within:
- 24 hours for NHS App messages
- 72 hours for emails
- 72 hours for text messages
Your message will have a 'failed' status if it's not delivered within this time. Find out more about message, channel and supplier statuses (opens in a new tab).
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 use. You'll be given your routing plan IDs during onboarding. If you're sending messages written by your users in your software, use a routing plan ID that matches the message channel they'll send with (opens in a new tab). |
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_ {fieldName} |
No | String |
The personalisation fields used in the message templates that will be sent to your recipients. If you have multiple personalisation fields, add a new column for each in the following format: personalisation_{fieldName} If you're sending messages written by your users in your software, set up your free-text inputs to populate one of our personalisation fields. Then use the personalisation field that matches the message channel your user will send with (opens in a new tab). |
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.
You'll need to provide compelling evidence to our onboarding team if you wish to temporarily override (replace) the contact details.
NHS Notify will consult with relevant NHS England legal and clinical teams for approval.
Add the following columns to your CSV to override the 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 recipient's 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 |
| recipient_contactDetails_name_firstName | No (disabled by default) | String | The recipient's first name | John |
| recipient_contactDetails_name_middleNames | No (disabled by default) | String | The recipient's middle names | Andrew Robert |
| recipient_contactDetails_name_lastName | No (disabled by default) | String | The recipient's last name. If you want to override the recipient's name, you must include the last name in your request | Smith |
| recipient_contactDetails_name_prefix | No (disabled by default) | String | The prefix of the recipient's name | Dr. |
| recipient_contactDetails_name_suffix | No (disabled by default) | String | The suffix of the reicpient's name | Jr. |
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. |
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
Last edited: 13 May 2025 3:17 pm