Skip to main content
Message Exchange for Social Care and Health (MESH) API

Transfer messages and large files securely across health and social care organisations using the Message Exchange for Social Care and Health (MESH) API.

Overview

Use this API to securely transfer healthcare data between organisations using the Message Exchange for Social Care and Health (MESH), which is a component of Spine.

You interact with MESH via a virtual mailbox, only accessible to your organisation, by making calls to this API from your application.

You can:

  • check the number of messages in your inbox
  • get the messageIds of messages in your inbox that are ready for download
  • download a message, or a larger message which was sent to you as a series of chunks
  • acknowledge the successful download of a message, which removes it from your inbox
  • look up the mailbox of an organisation you want to send data to
  • send a message, or a larger message as series of chunks
  • track the status of messages that you sent from your outbox
  • validate your mailbox every 24 hours to let Spine know it's still active

Messages must have a:

  • sender mailbox ID
  • receiver mailbox ID
  • workflow ID provided by MESH, that identifies what type of data the message contains, so the receiving organisation knows how to process it. For example, the receiver might process X-ray image data differently from blood test results.

You can also interact with MESH via a Java-based MESH client or a web-based MESH User Interface.


Who can use this API

This API can only be used where there is a legal basis to do so. You should make an access request before you go too far with your development.

You must have made this request before you can go live (see 'Onboarding' below).


Prerequisites

You must register with MESH to use the API. As part your registration, we will provide you with these items:

  • MESH mailbox (with a unique ID and password)
  • client Transport Layer Security (TLS) certificates
  • environment shared secret
  • list of workflow IDs to identify types of messages your organisation will send and receive

A number of our APIs are messaging APIs that use MESH as the transport layer. For a full list, see our API catalogue, filtered on MESH APIs.

In particular, this includes National Event Management Service - FHIR API - our API for publishing and subscribing to healthcare events such as updates to patient demographic details.


API status and roadmap

This API is currently stable.

To see our roadmap, or to suggest, comment or vote on features for this API, see our interactive product backlog.


Technology

This API is RESTful.


Network access

This API is available on the internet and, indirectly, on the Health and Social Care Network (HSCN).

For more details see Network access for APIs.


Environments and testing

There are several independent, externally accessible instances of MESH for use by parties external to NHS Digital for testing, each with a different root URL.

Some environments require a connection to the HSCN network.

Purpose Network availabiity URL
Development HSCN https://msg.dev.spine2.ncrs.nhs.uk/
Integration HSCN https://msg.int.spine2.ncrs.nhs.uk/
Integration Internet https://msg.intspineservices.nhs.uk/
Deployment HSCN https://msg.dep.spine2.ncrs.nhs.uk/
Production HSCN https://mesh-sync.national.ncrs.nhs.uk/
Production Internet https://mesh-sync.spineservices.nhs.uk/

Note - each environment has the same shared secret but requires different client TLS certificates. For any questions about our testing environments, contact our support mailbox itoc.supportdesk@nhs.net.

Develop against a local MESH sandbox server

There is an existing (unsupported) example of a RESTful interface on GitHub. This Python client also contains a mock MESH server which you can run locally without any real MESH credentials.

With the example RESTful MESH client installed, you can run the mock server with:

The client TLS certificates which you need to connect to the mock server are in the Python library. You can either copy them from the python library directory to your working directory, or download them from:

  • client.cert.pem
  • client.key.pem
  • ca.cert.pem

With the certificates in place, getting the URL should result in a Not Found error. Without the certificates, you will get a TLS error.


MESH Authorization header

Requests to the MESH API require an authorisation token in the HTTP Authorization header. To be valid, the authorisation token must match the schema described below. The token includes cryptographic hashes of your organisation's MESH mailbox password and the environment-wide shared secret. As an additional security measure each token which matches the schema is valid for one request only, so you must generate a new token for every request. Any repeated use of a token results in a 403: Not Authorized response from the MESH API.

The authorisation token is made up of six elements. With the exception of the first and second elements, each element is separated from the next by a colon (:).

Name Description
NHSMESH The name of the Custom Authentication Schema. The space at the end of the schema is important.
mailbox_id ID of the mailbox sending the HTTP Request. Must be uppercase.
nonce A GUID used as an encryption nonce.
nonce_count The number of times that the same nonce has been used.
timestamp The current date and time in yyyyMMddHHmm format.
hash HMAC-SHA256 hash - see the list below.

The hash is compiled of the following items:

  • The key is the MESH environment shared secret
  • The message is the concatenation of the 5 following elements, joined by a colon (:):
    • mailbox_id - same as element 2
    • nonce - same as element 3
    • nonce_count - same as element 4
    • mailbox_password - The password for the MESH mailbox
    • timestamp - same as element 5

Changing the nonce and/or nonce_count elements between requests ensures the Authorization header is unique and valid.

Notes

  • the API rejects the request if the timestamp supplied is not within 2 hours of the server time
  • in the example below HMACSECRETKEY has been [REDACTED], this is the 'environment shared secret' which you received as part of creating your mailbox

Example implementation

Here is an implementation of the above in python3.


MESH API pseudocode

To use MESH effectively, use the following flow of API calls:

  • inbox poll cycle
  • outbox workflow

Validate your mailbox once every 24 hours using the 'Validate a mailbox' endpoint.

Inbox poll cycle

Spine gives each message a unique messageID after you post it to your outbox. It is the primary identifier for the message during MESH transit.

Poll your mailbox at most every 5 minutes, but at least every 24 hours. The pseudocode for a mailbox poll is:

  1. Poll to get the messageIds of messages ready to download from the 'Check an inbox' endpoint.
  2. For each messageID returned in step 1:
    • download the message with the 'Download message' endpoint
    • if it's identified as a chunked message, download all remaining chunks with the 'Download message chunk' endpoint
    • acknowledge receipt of the message via the 'Acknowledge message' endpoint
  3. Repeat step 2 until you have processed the number of messages returned in step 1.
  4. If you received exactly 500 messages in step 1 then repeat from step 1, immediately polling again and downloading, until you receive 0 messages in step 1.

Asynchronous error reporting

Most problems with message transfer are indicated synchronously (immediately) when you call the 'Send Message' endpoint. However, some errors might occur after a successful request (asynchronously). You get any error reports as messages in your inbox, which you need to receive as part of your inbox poll cycle. Error reports differ from regular messages in these ways:

  • the 'Download message endpoint' has a different value for the Mex-Messagetype header:
    • DATA for a normal organisation-to-organisation message
    • REPORT for an error report
  • the Download message response body of an error report message is empty

We strongly recommend you check the value of Mex-Messagetype after downloading each message so you can take appropriate action if needed.

Error Report Header Description
Mex-Statusevent Step in the MESH server side process when the error occurred
Mex-Linkedmsgid The messageId of the undelivered message
Mex-Workflowid The workflowId of the undelivered message
Mex-Statustimestamp Time the error occurred
Mex-Localid Sender assigned localId of the unacknowledged message
Mex-Statuscode Indicate the status of the message, non-00 indicates error
Mex-Messageid The messageId of the error report (not the undelivered message)
Mex-Statussuccess SUCCESS or ERROR (is always ERROR in an error report)
Mex-Statusdescription Indicate the status the message, non-00 indicates error
Mex-To Intended receiver of the undelivered message
Mex-Messagetype REPORT
Mex-Subject The subject of the undelivered message

Error codes

Some of the below errors are only applicable for some API calls. For example, error code 15 would only be found when calling 'Child Protection Information Services' (CP-IS).

Error code Typical description
02 Data file is missing or inaccessible
06 Malformed headers
07 Invalid From Address, the mailbox does not match the authorization header
08 Missing Mex-To header
11 Invalid Message Type for the transfer, should be DATA
12 Unregistered to address
14 Undelivered message
15 Bad 'Child Protection - Information Sharing' (CP-IS) File
16 Sender is not allowed to send messages of this type
17 Receiver not registered for workflowId
19 workflowId does not support chunked files

Outbox workflow

The maximum amount of data allowed by MESH in a single request message is 100MB over HSCN conections or 20MB over the internet. You can send larger messages by breaking them into "chunks" that are transmitted as a single message over multiple requests. The upper limit of a single chunked message is 20GB.

The MESH UI and older versions of the MESH client do not support chunking. Check that the receiver's interface to MESH for your workflowId handles chunked messages prior to sending. To do this:

  1. Determine the size of your message data (after compression) with a standard algorithm (such as gzip). If the compressed message is larger than 100MB or 20MB if sending over the internet, is smaller than 20GB, and the receiving mailbox / workflowId supports chunking, then you can send a chunked message. To prepare for this:
    • split the uncompressed data into ordered chunks
    • independently compress each chunk with the same compression algorithm (such as gzip) such that each chunk is smaller than 100MB
    • use the first chunk (after compression) as the initial message data
  2. Send a message with appropriate workflowId, receiver and mailboxId. To do this:
    • optionally include localId from step 2 for tracking. This field must not contain PID.
    • if sending a chunked message, include an extra header to indicate that this is the first in a series of chunks, then submit the subsequent chunks via the 'Send Chunked Message' endpoint
  3. A messageID will be returned which is the unique identifer and can be used for tracking and helping with incident resolution. It would be good practice to log this identifier.

Message expiration

Messages that are not downloaded and acknowledged within five days of delivery are removed from your inbox. The sending organisation receives an error report explaining that the receiver did not collect the message. Uncollected messages are completely deleted from the MESH server 30 days after the initial delivery. If the sending organisation cannot re-send the message within the intervening time, it may contact the NHS Digital national service desk with the error report details and ask for the message to be placed in your inbox again.


Onboarding

You need to get your software approved by us before it can go live with this API. We call this onboarding. The onboarding process can sometimes be quite long, so it's worth planning well ahead:

For any other queries, contact our support mailbox ssd.nationalservicedesk@nhs.net.


Endpoints

Acknowledge message

put
/messageexchange/{mailboxID}/inbox/{messageID}/status/acknowledged

Overview

Use this endpoint to acknowledge the successful download of a message.

This operation:

  • closes the message transaction on Spine
  • removes the message from your mailbox inbox, which means that the messageId does not appear in subsequent calls to the 'Check inbox' endpoint and cannot be downloaded again

If you fail to acknowledge a message after five days in the inbox this sends a non-delivery report to the sender's inbox.

Request
Response

Request

Path parameters
Name Description
messageID

String

The ID of the message

Required
mailboxID

String

The ID of the mailbox

Example: MAILBOX01

Required
Headers
Name Description
Authorization

String

Authentication headers

Example: Authorization: NHSMESH NONFUNC01:jt81ti68rlvta7379p3ng949rv:1:201511201038:291259e6a73cde3278f99cd5bd3c7ec9b3d1d5479077a8f711bddf58073d5555

Required

Response

HTTP status: 200

OK

Body

Content type: application/json

Schema

Name Description
object
messageID
string
Example: 20200529155357895317_3573F8
HTTP status: 403

Authentication failed

Body

Content type: application/json

Schema

Name Description
object
messageID
string

ID of the allocated message

Example: 20200529155357895317_3573F8
errorEvent
string

Status event

Example: status event
errorCode
integer

Status code

Example: 403
errorDescription
string

Description of the status

Example: Description of the status

Check an inbox

get
/messageexchange/{mailboxID}/inbox

Overview

Use this endpoint to return the messageId of messages in the mailbox inbox ready for download. Client systems MUST poll their assigned inbox a minimum of once a day and a maximum of once every five minutes for messages (unless there are more messages waiting to download).

A maximum of 500 messageId are returned in every request. Continue the polling and download cycle until you empty the mailbox and you receive less than 500 messages in the response.

Request
Response

Request

Path parameters
Name Description
mailboxID

String

The ID of the mailbox

Example: MAILBOX01

Required
Headers
Name Description
Authorization

String

Authentication headers

Example: Authorization: NHSMESH NONFUNC01:jt81ti68rlvta7379p3ng949rv:1:201511201038:291259e6a73cde3278f99cd5bd3c7ec9b3d1d5479077a8f711bddf58073d5555

Required

Response

HTTP status: 200

OK

Body

Content type: application/json

Schema

Name Description
object
messages
array

Array of strings of messageId in inbox

string
HTTP status: 400

Bad Request

Body

Content type: application/json

Schema

Name Description
object
HTTP status: 403

Authentication failed

Body

Content type: application/json

Schema

Name Description
object
errorEvent
string

Status event

Example: status event
errorCode
integer

Status code

Example: 403
errorDescription
string

Description of the status

Example: Description of the status

Check an inbox count (deprecated)

get
/messageexchange/{mailboxID}/count

Overview

Use this endpoint to check the number of messages currently held in the MESH mailbox that are ready to download.

This endpoint is now deprecated as it is not needed as part of the polling cycle.

Request

Path parameters
Name Description
mailboxID

String

The ID of the mailbox

Example: MAILBOX01

Required
Headers
Name Description
Authorization

String

Authentication headers

Example: Authorization: NHSMESH NONFUNC01:jt81ti68rlvta7379p3ng949rv:1:201511201038:291259e6a73cde3278f99cd5bd3c7ec9b3d1d5479077a8f711bddf58073d5555

Required

Response

HTTP status: 200

OK

Body

Content type: application/json

Schema

Name Description
object
count
integer

number of messages in mailbox

internalID
string

Internal reference for diagnosis of errors

Example: 20200603094542820500_AEA7BA_1573484974
allResultsIncluded
boolean

In rare cases not all results can be included, if false the mailbox needs to download.

HTTP status: 400

Bad Request

Body

Content type: application/json

Schema

Name Description
object
HTTP status: 403

Authentication failed

Body

Content type: application/json

Schema

Name Description
object
errorEvent
string

Status event

Example: status event
errorCode
integer

Status code

Example: 403
errorDescription
string

Description of the status

Example: Description of the status

Download message

get
/messageexchange/{Recipient}/inbox/{messageID}

Overview

Use this endpoint to retrieve a message based on the messageid obtained from the 'Check Inbox' endpoint.

Message expiration

Messages you do not download and acknowledge within five days of delivery are removed from your inbox. The sending organisation receives an error report explaining that the receiver did not collect the message. Uncollected messages are completely deleted from the MESH server 30 days after initial delivery. If the sending organisation cannot re-send the message within the intervening time, they can contact the NHS Digital national service desk with the error report details and ask for the message to be re-sent.

Report Messages

The Mex-Messagetype header indicates if the payload is a DATA message or a REPORT.
Error reports differ from regular messages in these ways:

  • the Download message endpoint has a different value for the Mex-Messagetype header
    • DATA for a normal organisation-to-organisation message
    • REPORT for an error report
  • the Download message response body of an error report message is empty
Request
Response

Request

Path parameters
Name Description
messageID

String

The ID of the message

Required
Recipient

String

Recipient mailbox ID

Example: {Recipient Mailbox ID}

Required
Headers
Name Description
Authorization

String

Authentication headers

Example: Authorization: NHSMESH NONFUNC01:jt81ti68rlvta7379p3ng949rv:1:201511201038:291259e6a73cde3278f99cd5bd3c7ec9b3d1d5479077a8f711bddf58073d5555

Required

Response

HTTP status: 200

OK

Body

Content type: application/json

Schema

Name Description
object
HTTP status: 206

Partial download – Indicates that chunk has been downloaded successfully and that there are further chunks.

Body

Content type: binary

Schema

Name Description
object
HTTP status: 403

Authentication failed

Body

Content type: application/json

Schema

Name Description
object
messageID
string

ID of the allocated message

Example: 20200529155357895317_3573F8
errorEvent
string

Status event

Example: status event
errorCode
integer

Status code

Example: 403
errorDescription
string

Description of the status

Example: Description of the status
HTTP status: 410

Gone, message has already been downloaded and acknowledged

Body

Content type: application/json

Schema

Name Description
object

Download message chunk

get
/messageexchange/{Recipient}/inbox/{messageID}/{chunkNo}

Overview

Use this endpoint to download a chunked message. Initially, call the 'Download Message' endpoint with the messageId given by the 'Check Inbox' endpoint as usual. When the message is chunked, the 'Download message' endpoint response differs in two ways:

  • the response code is '206: Partial Content' (instead of '200: OK')
  • the response headers contain Mex-Chunk-Range: 1:n

This endpoint is used to download the remaining n-1 chunks.

Request

Following on from the example in the 'Send chunked message' endpoint, Alice checks her inbox and sees a new message.

She downloads the first part of the message. Note this use of curl uses the --include argument, to show the value of the HTTP headers in the MESH response.

Here we have added the --include argument to curl which prints more response information, including the HTTP response code and response headers. (tr -d '\r' invokes a linux utility to strip carriage returns from the end of each of the lines added to the curl --include argument).

Alice notes that the response code is 206 Partial Content - meaning it is the first part of a chunked message. How much of the message remains is given by the Mex-Chunk-Range header, 1:2 indicating the response body is the first of two parts.

Alice makes another call to retrieve the second part of the message.

That this is the final part of the message is indicated in two ways:

  • the response code is 200 OK rather than 206 Partial Content
  • the Mex-Chunk-Range response header is 2:2

Request

Path parameters
Name Description
Recipient

String

Recipient mailbox ID

Example: {Recipient Mailbox ID}

Required
messageID

String

The ID of the message

Required
chunkNo

Integer

The index number of the chunk

Example: 1

Required
Headers
Name Description
Authorization

String

Authentication headers

Example: Authorization: NHSMESH NONFUNC01:jt81ti68rlvta7379p3ng949rv:1:201511201038:291259e6a73cde3278f99cd5bd3c7ec9b3d1d5479077a8f711bddf58073d5555

Required

Response

HTTP status: 200

OK

Body

Content type: application/json

Schema

Name Description
object
HTTP status: 206

Partial download – Indicates that chunk has been downloaded successfully and that there are further chunks.

Body

Content type: binary

Schema

Name Description
object
HTTP status: 403

Authentication failed

Body

Content type: application/json

Schema

Name Description
object
messageID
string

ID of the allocated message

Example: 20200529155357895317_3573F8
errorEvent
string

Status event

Example: status event
errorCode
integer

Status code

Example: 403
errorDescription
string

Description of the status

Example: Description of the status
HTTP status: 404

Message does not exist

Body

Content type: application/json

Schema

Name Description
object

Look up MESH address

get
/endpointlookup/mesh/{odsCode}/{Mex-workflowid}

Overview

Use this endpoint to search for the mailbox of the organisation you want to send data to, using their unique Organisation Data Service (ODS) code, their MESH mailboxID and the agreed workflowId for the data.

An example call:

Request
Response

Note: neither the ods-code nor workflowId in this example are real.

Request

Path parameters
Name Description
odsCode

String

All health and social care organisations have a unique ODS code

Example: SCREEN2

Required
Mex-workflowid

String

Workflow ID

Example: {Workflow ID}

Required
Headers
Name Description
Authorization

String

Authentication headers

Example: Authorization: NHSMESH NONFUNC01:jt81ti68rlvta7379p3ng949rv:1:201511201038:291259e6a73cde3278f99cd5bd3c7ec9b3d1d5479077a8f711bddf58073d5555

Required

Response

HTTP status: 200

OK

Body

Content type: application/json

Schema

Name Description
object
query_id
string
Example: 20200601131040203367_A441C2_1573484974
results
array
string
HTTP status: 403

Message does not exist

Body

Content type: application/json

Schema

Name Description
object

Track outbox

get
/messageexchange/{mailboxID}/outbox/tracking

Overview

Use this endpoint to enquire about the status of messages sent from your outbox. When determining the frequency of the calling of this endpoint consider that MESH is asynchronous and it might be some hours until the recipient downloads your message. You must not poll this endpoint frequently.

The messageId is the value returned in the response to a message upload.

Do not use this endpoint to replace a business ack message. If the business process requires confirmation that the recipient has processed the message then send a business ACK over MESH. The convention is to use the same workflowId appended with _ACK).

Request

It is possible for Bob to check the status of the chunked message he sent to Alice. (Note that in this example, Alice has not acknowledged the chunked message she received from Bob).

Response

Suppose Alice only now acknowledges the message Bob sent.

Request
Response

The next call to Track outbox by Bob

Request
Response

This shows the status field of the response has changed from Accepted to Acknowledged. All of the fields in the previous response are also included.

Request

Path parameters
Name Description
mailboxID

String

The ID of the mailbox

Example: MAILBOX01

Required
Query parameters
Name Description
messageID

String

Value of messageID returned in the send message response

Example: 20210311101813838554_1B8F53

Required
Headers
Name Description
Authorization

String

Authentication headers

Example: Authorization: NHSMESH NONFUNC01:jt81ti68rlvta7379p3ng949rv:1:201511201038:291259e6a73cde3278f99cd5bd3c7ec9b3d1d5479077a8f711bddf58073d5555

Required

Response

HTTP status: 200

OK

Body

Content type: application/json

Schema

Name Description
object
processId
string
addressType
string
Example: ALL
localId
string
Example: api-docs-bob-sends-alice-a-chunked-file
recipientBillingEntity
string
Example: England
dtsId
string
Example: 20210311101813838554_1B8F53
statusSuccess
string
messageType
string
Example: DATA
statusTimestamp
string
senderBillingEntity
string
Example: England
senderOdsCode
string
Example: X26
partnerId
string
recipientName
string
Example: APIM bebop
senderName
string
Example: APIM bebop
subject
string
statusEvent
string
version
string
Example: 1.0
encryptedFlag
string
statusDescription
string
senderOrgName
string
Example: TEST Org Partnership Trust
status
string
Example: Accepted
workflowId
string
Example: API-DOCS-TEST
senderOrgCode
string
Example: TestOrg
recipientOrgName
string
Example: TEST Org Partnership Trust
expiryTime
string
Example: 20200606122153
senderSmtp
string
Example: x26hc006@dts.nhs.uk
fileName
string
Example: message.txt.gz
recipientSmtp
string
Example: x26hc005@dts.nhs.uk
meshRecipientOdsCode
string
Example: X26
compressFlag
string
uploadTimestamp
string
Example: 20200601122152
recipient
string
Example: X26HC005
sender
string
Example: X26HC006
checksum
string
isCompressed
string
contentEncoding
string
Example: gzip
recipientOrgCode
string
Example: TestOrg
messageId
string
Example: 20210311101813838554_1B8F53
statusCode
string
fileSize
integer
Example: 187
HTTP status: 403

Message does not exist

Body

Content type: application/json

Schema

Name Description
object

Track outbox (deprecated)

get
/messageexchange/{mailboxID}/outbox/tracking/{localID}

Overview

This endpoint is now deprecated tracking?messageID should be used instead.

Request

Path parameters
Name Description
mailboxID

String

The ID of the mailbox

Example: MAILBOX01

Required
localID

String

Value of Mex-LocalID provided by sender

Example: api-docs-bob-sends-alice-a-chunked-file

Required
Headers
Name Description
Authorization

String

Authentication headers

Example: Authorization: NHSMESH NONFUNC01:jt81ti68rlvta7379p3ng949rv:1:201511201038:291259e6a73cde3278f99cd5bd3c7ec9b3d1d5479077a8f711bddf58073d5555

Required

Response

HTTP status: 200

OK

Body

Content type: application/json

Schema

Name Description
object
processId
string
addressType
string
Example: ALL
localId
string
Example: api-docs-bob-sends-alice-a-chunked-file
recipientBillingEntity
string
Example: England
dtsId
string
Example: 20200601122152994285_D59900
statusSuccess
string
messageType
string
Example: DATA
statusTimestamp
string
senderBillingEntity
string
Example: England
senderOdsCode
string
Example: X26
partnerId
string
recipientName
string
Example: APIM bebop
senderName
string
Example: APIM bebop
subject
string
statusEvent
string
version
string
Example: 1.0
encryptedFlag
string
statusDescription
string
senderOrgName
string
Example: TEST Org Partnership Trust
status
string
Example: Accepted
workflowId
string
Example: API-DOCS-TEST
senderOrgCode
string
Example: TestOrg
recipientOrgName
string
Example: TEST Org Partnership Trust
expiryTime
string
Example: 20200606122153
senderSmtp
string
Example: x26hc006@dts.nhs.uk
fileName
string
Example: message.txt.gz
recipientSmtp
string
Example: x26hc005@dts.nhs.uk
meshRecipientOdsCode
string
Example: X26
compressFlag
string
uploadTimestamp
string
Example: 20200601122152
recipient
string
Example: X26HC005
sender
string
Example: X26HC006
checksum
string
isCompressed
string
contentEncoding
string
Example: gzip
recipientOrgCode
string
Example: TestOrg
messageId
string
Example: 20200601122152994285_D59900
statusCode
string
fileSize
integer
Example: 187
HTTP status: 300

Multiple options (The localId provided with the message was not unique)

Body

Content type: application/json

Schema

Name Description
object
HTTP status: 403

Message does not exist

Body

Content type: application/json

Schema

Name Description
object

Send chunked message

post
/messageexchange/{mailboxID}/outbox/{messageID}/{chunkNo}

Overview

Use this endpoint to send a chunked message. The 'Send Message' endpoint has a maximum single request message payload size of 100MB over HSCN or 20MB over the internet. However, you can send much larger messages (up to 20GB) by breaking up the message into chunks and transmitting it over multiple requests.

Note: Some workflowIDs do not support chunking because it is not currently supported in the MESH UI and older versions of the MESH client. Check with your receiving organisation before sending messages with this endpoint. To send a chunked message:

  1. Split it into separate files
  2. Compress the individual chunks separately with the same compression program (e.g. gzip).
    • DO NOT compress a large file and then split the compressed version
  3. Upload the first file using the normal 'Send message' endpoint.
    • include the Mex-Chunk-Range header with a value of 1:n where n is the number of separate files your big data is split into
    • capture the messageId field in the returned JSON
  4. Upload subsequent files in the correct order using the chunked message endpoint

Note: fewer headers are required for the chunked message endpoint because Spine uses the relevant metadata from the initial (Mex-Chunk-Header=1:n) call to the 'Send message' endpoint.

Request

Suppose Bob has a large file to send to Alice. In this example we will use message.txt. It is easily small enough to send in a single request but we will chunk it anyway to illustrate the API calls.

First we break up our one "large" file into two smaller files. We will transmit one per request.

Large messages should be compressed to reduce the bandwidth and storage requirements for Spine.

Request

Path parameters
Name Description
mailboxID

String

The ID of the mailbox

Example: MAILBOX01

Required
messageID

String

The ID of the message

Required
chunkNo

Integer

The index number of the chunk

Example: 1

Required
Headers
Name Description
Authorization

String

Authentication headers

Example: Authorization: NHSMESH NONFUNC01:jt81ti68rlvta7379p3ng949rv:1:201511201038:291259e6a73cde3278f99cd5bd3c7ec9b3d1d5479077a8f711bddf58073d5555

Required
Content-Type

String

Type of sent content

Example: application/octet-stream

Required
Mex-Chunk-Range

String (integer:integer)

describes which chunk of the range is sent.

Example: 124

Required

Response

HTTP status: 202

Accepted

Body

Content type: application/json

Schema

Name Description
object
messageID
string

Unique message ID, identical to initial Send message endpoint

Example: 20200529155357895317_3573F8
blockID
integer

ID assigned to the block

HTTP status: 403

Authentication failed

Body

Content type: application/json

Schema

Name Description
object
messageID
string

ID of the allocated message

Example: 20200529155357895317_3573F8
errorEvent
string

Status event

Example: status event
errorCode
integer

Status code

Example: 403
errorDescription
string

Description of the status

Example: Description of the status

Send message

post
/messageexchange/{mailboxID}/outbox

Overview

Use this endpoint to send a message via MESH. Use the POST command to your virtual outbox. Specify the message recipient in the request headers, with the message contained in the request body.

Messages larger than 100MB

100MB (20MB on internet) is the largest data payload the MESH API accepts in a single request. Compress larger messages to reduce bandwidth and data storage on Spine. If compression does not sufficiently reduce the message size enough for transmission in a single request then you can break it up into smaller chunks and transmit them separately provided:

  1. The total compressed size of the message is < 100MB - this is the Spine upper limit for a single message.
  2. The receiver mailboxId and workflowId support the downloading of chunked messages. MESH UI and older versions of the MESH client do not support this.

To correctly break the outbound message into valid chunks:

  1. Split the uncompressed message into n ordered chunks such that each (compressed) chunk is smaller than 20MB.
  2. Independently compress each chunk with the same compression algorithm (e.g. gzip).
  3. The first (compressed) chunk of the message should be transmitted using this endpoint (the normal send message endpoint). Include the optional Mex-Chunk-Range header with a value 1:n to tell Spine that this is a chunked message and to wait for n-1 other requests before delivering the message. The messageId of this initial server response must be captured as it is a required path element of the Send chunked message URL.

Always set the workflowId as some workflowIds are restricted which means the mailbox sender and recipient must be configured for the workflowId you send.

To discover the recipient mailbox either use the endpointlookup endpoint or for certain workflows you can include demographic details in the Mex-To field.

It is good practice to capture the returned messageId as this provides a unique identifer which you can use for message tracking.

Request
Response

Request

Path parameters
Name Description
mailboxID

String

The ID of the mailbox

Example: MAILBOX01

Required
Headers
Name Description
Authorization

String

Authentication headers

Example: Authorization: NHSMESH NONFUNC01:jt81ti68rlvta7379p3ng949rv:1:201511201038:291259e6a73cde3278f99cd5bd3c7ec9b3d1d5479077a8f711bddf58073d5555

Required
Content-Type

String

Type of sent content

Example: application/octet-stream

Required
Mex-FileName

String

{Original File Name}

Example: {Message content should have this file name after receipt}

Required
Mex-From

String

Sending organisation's mailbox ID

Example: {Sending organisation's mailbox ID}

Required
Mex-To

String

Recipient mailbox ID

Example: {Recipient Mailbox ID}

Required
Mex-WorkflowID

String

Identifies the Business Workflow associated with the message

Example: {Workflow ID}

Required
Mex-Chunk-Range

String

1:{n} {if first of n chunks, see Send chunked message}

Mex-Content-Compress

String

Flag to indicate that the contents have been automically compressed by the client using GZip compression

Mex-Content-Encrypted

String

Indicate to the receiver that contents are encrypted

Mex-Localid

String

A unique ID generated by you, must not contain Patient Identifiable Data PID

Mex-Subject

String

Subject line for message to SMTP MESH mailboxes

Content-Encoding

String

Algorithm used to compress the file e.g. 'gzip'

Mex-MessageType

String

DATA

Required
Mex-ProcesslID

String

{Local process identifer}

mex-Content-Checksum

String

Checksum of the original file contents

Response

HTTP status: 202

Accepted

Body

Content type: application/json

Schema

Name Description
object
messageID
string

Unique Id assigned by the MESH server

Example: 20200529155357895317_3573F8
HTTP status: 403

Authentication failed

Body

Content type: application/json

Schema

Name Description
object
messageID
string

ID of the allocated message

Example: 20200529155357895317_3573F8
errorEvent
string

Status event

Example: status event
errorCode
integer

Status code

Example: 403
errorDescription
string

Description of the status

Example: Description of the status
HTTP status: 417

Invalid Recipient or the workflow is restricted

Body

Content type: application/json

Schema

Name Description
object
messageID
string

ID of the allocated message

errorEvent
string

Status event

errorCode
integer

Status code

Example: 417
errorDescription
string

Description of the status

Validate a mailbox (Handshake)

get
/messageexchange/{mailboxID}

Overview

Use this endpoint to check that MESH can be reached and that the authentication you are using is correct. This endpoint only needs to be called once every 24 hours. This endpoint updates the details of the connection history held for your mailbox and is similar to a keep-alive or ping message, in that it allows monitoring on the Spine to be aware of the active use of a mailbox despite a lack of traffic.

Request
Response

Request

Path parameters
Name Description
mailboxID

String

The ID of the mailbox

Example: MAILBOX01

Required
Headers
Name Description
Authorization

String

Authentication headers

Example: Authorization: NHSMESH NONFUNC01:jt81ti68rlvta7379p3ng949rv:1:201511201038:291259e6a73cde3278f99cd5bd3c7ec9b3d1d5479077a8f711bddf58073d5555

Required
Mex-ClientVersion

String

Client version number

Example: ApiDocs==0.0.1

Required
Mex-OSName

String

Operating system name

Example: Linux

Required
Mex-OSVersion

String

Operating system version

Example: #44~18.04.2-Ubuntu

Required
Mex-OSArchitecture

String

{Operating System Architecture}

Mex-JavaVersion

String

{JVM Version Number}

Response

HTTP status: 200

OK

Body

Content type: application/json

Schema

Name Description
object
HTTP status: 400

Bad Request

Body

Content type: application/json

Schema

Name Description
object
HTTP status: 403

Authentication failed

Body

Content type: application/json

Schema

Name Description
object
messageID
string

ID of the allocated message

Example: 20200529155357895317_3573F8
errorEvent
string

Status event

Example: status event
errorCode
integer

Status code

Example: 403
errorDescription
string

Description of the status

Example: Description of the status