{"openapi":"3.0.2","info":{"contact":{"email":"ssd.nationalservicedesk@nhs.net","name":"National Service Desk"},"description":"## Overview\n\nYou interact with MESH by making calls to this API from your application.\n\nWith the API, you can:\n\n- check the number of messages in your inbox\n- send a message, or a larger message as series of chunks\n- download a message, or a larger message which was sent to you as a series of chunks\n- acknowledge the successful download of a message, which removes it from your inbox\n- get the identifiers of messages in your inbox that are ready for download\n- track the status of messages that you sent from your outbox\n- look up the mailbox of an organisation you want to send data to\n- validate your mailbox every 24 hours to let Spine know it's still active\n\n## Who can use this API\n\nThis API can only be used where there is a legal basis to do so. We'll ask you to demonstrate this as part of the digital onboarding process before your software goes live.\n\n## Requirements for using this API\nThere are 2 parts to getting the MESH API, these are:\n\n1. developing and integrating your software\n2. getting your software approved to go live\n\n### 1. Developing and integrating your software\n\nYou'll need some things at different stages of your development to integrate with the MESH API.\nFor each environment you use, you'll need a:\n- MESH mailbox ID and password\n- Transport Layer Security (TLS) certificate\n- shared secret to include in the MESH authorization header\n\n### 2. Getting your software approved to go live\n\nThis is also called digital onboarding. You'll need to submit information that demonstrates:\n- you have a valid use case\n- you can manage risks\n- your software conforms technically with the requirements for this API\n\n## End-to-end process to integrate with MESH API\n\nThe length of time it takes to get your software live depends on the resources your organisation puts into:\n- developing your software\n- getting things you need for your integration like TLS certificates\n- completing onboarding processes and waiting for approval\n\nYou can do some things while you wait, but expect the end-to-end integration process to take 1 month or more.\n\n### Get started\n\nTo get started, sign in or create a developer account for digital onboarding, complete the 'Setup and eligibility' section and submit it.\n\nIf you're new to digital onboarding, add your product and select 'MESH' from the 'APIs to be used' list.\nSubmitting this information shows us that you have a legal basis to use the MESH API. We'll review the information you submit and respond within 5 to 10 working days.\n\nIf we approve your request to use the MESH API, we'll also email you a supplier pack within 10 working days. Read through this as it contains the testing requirements you'll need to fulfil later on.\n\nYou should get your use case approved before you go too far with development. You can choose to proceed with your integration while you wait for approval, but you'll be doing this at your own risk.\n\n [Sign in or create a developer account for digital onboarding](https://onboarding.prod.api.platform.nhs.uk)\n\n\nYou will receive a response within 10 working days.\n\nIf you have been approved to use the MESH API, our assurance team will contact you via email with a supplier pack containing the testing requirements you will need to fulfill. You will work alongside this team to get your solution assured.\n\n### Request a mailbox\n\nOnce we've approved your request to use the MESH API, you'll need to request a MESH Mailbox to use in a 'Path to Live integration environment'. This is how you'll interact with the MESH API. A MESH Mailbox is secure and only your organisation can access it.\n\nTo request a MESH Mailbox, you'll need to fill in an online form. It takes 5 to 10 minutes to complete.\n\nYou'll need to know:\n- your [ODS code](https://odsportal.digital.nhs.uk/)\n- the [workflow groups or IDs](https://digital.nhs.uk/services/message-exchange-for-social-care-and-health-mesh/workflow-groups-and-workflow-ids) for the files you plan to send or receive\n- the contact details of the person who will be managing the mailbox in your organisation\n\n[Request a 'Path to Live integration' MESH Mailbox](https://digital.nhs.uk/services/message-exchange-for-social-care-and-health-mesh/messaging-exchange-for-social-care-and-health-apply-for-a-mailbox)\n\n### Receive your credentials for the 'Path to Live integration' environment\n\nOnce you've requested a MESH Mailbox, we will email you your Mailbox ID and password within 5 working days. Keep these details safe as we'll also ask you for this if you need help from our support teams.\n\nYou will also receive the shared secret. You'll need to include this in the [MESH authorization header](#overview--mesh-authorization-header) when you develop this part of your software.\n\n### Get a TLS certificate\n\nYou'll need a TLS certificate to establish a secure connection to MESH.\n\nHow to get a TLS certificate\n\n1. Generate a private key using your preferred method, with the naming convention cn=mailboxid.odscode.api.mesh-client.nhs.uk\n2. Generate a certificate signing request (CSR) based on the private key and your Mailbox ID.\n3. Email the CSR to [itoc.supportdesk@nhs.net](mailto:itoc.supportdesk@nhs.net) - this needs to contain the common name from your CSR 'Subject' using the format local_id.ods_code.api.mesh-client.nhs.uk\n\nThe local_id is a local identifier such as a server name and ods_code is your ODS code, for example, SERVER001.X26.api.mesh-client.nhs.uk.\n\nOnce we receive your CSR, we'll send you a TLS certificate within 5 working days.\n\nDepending on how you implement MESH API, you may also need to [download a RootCA and SubCA certificate](https://digital.nhs.uk/services/path-to-live-environments/integration-environment#rootca-and-subca-certificates). These are also required to establish a secure connection.\n\n### Develop and test your software\n\nNow that you have a MESH Mailbox for a 'Path to Live integration' environment and a TLS certificate, start developing your software using the MESH API.\n\nWhen you're ready to go live, you'll need to:\n- request a TLS certificate for the production environment\n- request a MESH mailbox for the production environment\n- get a conformance certificate\n- sign a connection agreement\n\n### Submit non-functional requirements\n\nOnce you've developed your software, you'll need to answer some questions in digital onboarding about the processes you use for:\n- handling data securely\n- managing clinical risk\n- using our production environment\n\nThis shows that your software meets our non-functional requirements.\n\n[Sign in to the digital onboarding to answer questions on 'non-functional' requirements](https://onboarding.prod.api.platform.nhs.uk)\n\n### Demonstrate technical conformance\n\nBefore you can go live, in digital onboarding, you'll need to:\n- answer some questions to show you conform to the technical requirements of our APIs\n- upload a conformance certificate\n\nTo get a technical conformance certificate, you'll need to complete the testing requirements in the supplier pack we sent to you.\n\nSome of these tests have to be witnessed by us. To arrange a witness test, reply to the email that contains the supplier pack. The witness testing takes 2 to 3 hours.\n\nIn some cases, we may ask you to prepare test data a few days before the day of the witness testing.\n\nWhen you've completed a witness test, we'll email a technical conformance certificate to you within 5 working days. You can then upload it to digital onboarding.\n\n[Sign in to the digital onboarding to upload a technical conformance certificate](https://onboarding.prod.api.platform.nhs.uk)\n\n### Get a MESH Mailbox for your live software\n\nWhen you're ready to send or receive real data, you'll need a MESH Mailbox in the production environment. We'll ask to see the conformance certificate for your software before we issue this.\n\nMESH Mailboxes are specific to environments, this means you'll need a different MESH Mailbox ID for each environment you use.\n\nTo request a MESH Mailbox, you'll need to fill in an online form. It takes 5 to 10 minutes to complete.\n\nYou'll need to know:\n- your [ODS code](https://odsportal.digital.nhs.uk/)\n- the [workflow groups or IDs](https://digital.nhs.uk/services/message-exchange-for-social-care-and-health-mesh/workflow-groups-and-workflow-ids) for the files you plan to send or receive\n- the contact details of the person who will be managing the mailbox in your organisation\n\n[Request a 'Live' MESH Mailbox](https://digital.nhs.uk/services/message-exchange-for-social-care-and-health-mesh/messaging-exchange-for-social-care-and-health-apply-for-a-mailbox)\n\n### Get a TLS certificate for the production environment\n\nOnce you have a Mailbox ID, you'll need to get a TLS certificate. This allows you to establish a secure connection to MESH in the production environment.\n\nHow to get a TLS certificate\n1. Generate a private key using your preferred method, with the naming convention cn=mailboxid.odscode.api.mesh-client.nhs.uk\n2. Generate a CSR based on the private key and your Mailbox ID\n3. Email the CSR and technical conformance certificate to [ssd.nationalservicedesk@nhs.net](mailto:ssd.nationalservicedesk@nhs.net) - this needs to contain the common name from your CSR 'Subject' using the format local_id.ods_code.api.mesh-client.nhs.uk\n\nThe local_id is a local identifier such as a server name and ods_code is your ODS code, for example, SERVER001.X26.api.mesh-client.nhs.uk.\n\nOnce we receive your CSR and technical conformance certificate, we'll send you a TLS certificate for the production environment within 5 working days.\n\nDepending on how you implement MESH API, you may also need to [download a RootCA and SubCA certificate](https://digital.nhs.uk/services/path-to-live-environments/live-environment). These are also required to establish a secure connection.\n\n\n### Sign connection agreement\n\nYou'll need to sign a connection agreement before your software can go live. Once you've signed it, you need to upload it to the 'Legal agreement' section in digital onboarding. We'll email your connection agreement to you within 5 working days of completing your witness test.\n\n[Sign in to the digital onboarding to upload your connection agreement](https://onboarding.prod.api.platform.nhs.uk)\n\n### Go live with your software\n\nYou have now completed all integration and onboarding steps. This means you can use the MESH API with your live software.\n\n## Related APIs\nA 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](https://digital.nhs.uk/developer/api-catalogue?filter=mesh).\n\nIn particular, this includes [National Event Management Service - FHIR API](https://digital.nhs.uk/developer/api-catalogue/national-events-management-service-fhir) -\nour API for publishing and subscribing to healthcare events such as updates to patient demographic details.\n\n## API status and roadmap\nThis API is [in production](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses).\n\n## Service level\nThis API is a platinum service, meaning it is operational and supported 24 hours a day, 365 days a year.\n\nFor more details, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels).\n\n## Technology\nThis API is [RESTful](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#basic-rest).\n\n## Network access\nThis API is available on the internet.\n\nFor more details see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis).\n\n## Errors\nWe use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:\n\n* 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action\n* 400 to 499 if it failed because of a client error by your application\n* 500 to 599 if it failed because of an error on our server\n\nErrors specific to each API are shown in the Endpoints section, under Response. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors.\n\n## Open source\nWe have a number of open source resources that you might find useful:\n\n| Resource                   | Description                                                                                                                                                                    | Links                                                                                                                                                  |\n|----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|\n| MESH sandbox               | For early developer testing, a realistic MESH experience that runs locally in docker or as an embedded python package. For more details, see 'Environments and testing' below. | [GitHub repo](https://github.com/NHSDigital/mesh-sandbox) \\| [Python Package Index](https://pypi.org/project/mesh-sandbox/)                            |\n| MESH Python client         | A fully-featured Python client library that conforms to our technical integration requirements. This is not the same as the MESH Java client.                                  | [GitHub repo](https://github.com/NHSDigital/mesh-client) \\| [Python Package Index](https://pypi.org/project/Mesh-Client)                               |\n| MESH AWS Serverless client | A fully-featured MESH client built using terraform and AWS serverless components.                                                                                              | [GitHub repo](https://github.com/NHSDigital/terraform-aws-mesh-client)                                                                                 |\n| MESH Validate Auth Header  | A tool for validating the construction of the MESH authentication token.                                                                                                       | [GitHub repo](https://github.com/NHSDigital/mesh_validate_auth_header) \\| [GitHub pages UI](https://nhsdigital.github.io/mesh_validate_auth_header/#/) |\n\n\nFor more details, see [open source](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#open-source).\n\n## Environments and testing\nThere are multiple externally accessible instances of MESH that can be used for testing, each with a different root URL.\n\n\n| Purpose       | Network availability | URL                                       |\n|---------------|----------------------|-------------------------------------------|\n| Integration   | Internet             | `https://msg.intspineservices.nhs.uk/`    |\n| Production    | Internet             | `https://mesh-sync.spineservices.nhs.uk/` |\n\n**Note** - each environment has the same shared secret but requires different client TLS certificates.\n\nFor any questions about our testing environments, contact our support mailbox [itoc.supportdesk@nhs.net](mailto:itoc.supportdesk@nhs.net).\n\n### Develop against a local MESH sandbox server\nThere is a basic sandbox implementation of the MESH API available [mesh-sandbox](https://github.com/NHSDigital/mesh-sandbox).\n\nThis sandbox can be used for local development and currently does not require a client certificate\n\n## API Versioning\n\nMESH API now has `live-beta` support for versioning on certain endpoints in order to allow us to safely make new features and capabilities available to API consumers.\n\nMESH uses the `Accept` header to support different versions in the same API, sending a different `Accept` header will vary the response, refer to individual API endpoints for more detail.\n\nIf not specified `Accept: application/json` will be assumed and the lowest supported response version for that particular endpoint will be returned.\n\n**Note:** please refer to the table below for more detail on the status of a given API version.\n\n| Version | Accept                                               | Status |\n|---------|------------------------------------------------------|--------|\n| 1       | `application/json` or `application/vnd.mesh.v1+json` | live   |\n| 2       | `application/vnd.mesh.v2+json`                       | live   |\n\n## MESH Authorization header\nRequests to the MESH API require an authorisation token in the HTTP `Authorization` header.\nTo 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.\nAs 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.\n\nThe authorisation token is made up of six elements. Except for the first and second elements, each element is separated from the next by a colon (:).\n\n| Name          | Description                                                                                    |\n|---------------|------------------------------------------------------------------------------------------------|\n| `NHSMESH`     | The name of the Custom Authentication Schema. The space at the end of the schema is important. |\n| `mailbox_id`  | The mailbox identifier sending the HTTP Request. Must be uppercase.                            |\n| `nonce`       | A GUID used as an encryption nonce.                                                            |\n| `nonce_count` | The number of times that the same nonce has been used.                                         |\n| `timestamp`   | The current UTC date and time in `yyyyMMddHHmm` format.                                        |\n| `hash`        | HMAC-SHA256 hash - see the list below.                                                         |\n\nThe `hash` is compiled of the following items:\n\n* The `shared_key` is the MESH environment shared secret, provided by [itoc.supportdesk@nhs.net](mailto:itoc.supportdesk@nhs.net) as part of onboarding to the PTL environment.\n* The `message` is the concatenation of the 5 following elements, joined by a colon (:):\n  - `mailbox_id`\n  - `nonce`\n  - `nonce_count`\n  - `mailbox_password`\n  - `timestamp`\n\nChanging the `nonce` and/or `nonce_count` elements between requests ensures the Authorization header is unique and valid.\n\n**Notes**\n- the API rejects the request if the `timestamp` supplied is not within 2 hours of the server time\n- in the example below `SHARED_KEY` has been `[REDACTED_SHARED_KEY]`, this is the 'environment shared secret' which you received as part of creating your mailbox\n- in the example below `MAILBOX_PASSWORD` has been `[REDACTED_PASSWORD]`, this is the 'mesh mailbox password' which you received as part of creating your mailbox\n\n### Example implementation\nHere is an implementation of the above in `python3`.\n```python\n\"\"\" Python code to generate a valid authorization header. \"\"\"\nimport hmac\nimport uuid\nimport datetime\nfrom hashlib import sha256\n\nAUTH_SCHEMA_NAME = \"NHSMESH \"  # Note: Space at the end of the schema.\nSHARED_KEY = \"[REDACTED_SHARED_KEY]\"  # Note: Don't hard code your passwords in a real implementation.\n\n\ndef build_auth_header(mailbox_id: str, password: str = \"password\",  nonce: str = None, nonce_count: int = 0):\n    \"\"\" Generate MESH Authorization header for mailboxid. \"\"\"\n    # Generate a GUID if required.\n    if not nonce:\n        nonce = str(uuid.uuid4())\n    # Current time formatted as yyyyMMddHHmm\n    # for example, 4th May 2020 13:05 would be 202005041305\n    timestamp = datetime.datetime.utcnow().strftime(\"%Y%m%d%H%M\")\n\n    # for example, NHSMESH AMP01HC001:bd0e2bd5-218e-41d0-83a9-73fdec414803:0:202005041305\n    hmac_msg = mailbox_id + \":\" + nonce + \":\" + str(nonce_count) + \":\" + password + \":\" + timestamp\n\n    # HMAC is a standard crypto hash method built in the python standard library.\n    hash_code = hmac.HMAC(SHARED_KEY.encode(), hmac_msg.encode(), sha256).hexdigest()\n    return (\n            AUTH_SCHEMA_NAME # Note: No colon between 1st and 2nd elements.\n            + mailbox_id + \":\"\n            + nonce + \":\"\n            + str(nonce_count) + \":\"\n            + timestamp+ \":\"\n            + hash_code\n    )\n\n\n# example usage\nMAILBOX_ID = \"X26AB1234\" # Note: Don't hard code your mailbox id in a real implementation.\nMAILBOX_PASSWORD = \"[REDACTED_PASSWORD]\"  # Note: Don't hard code your passwords in a real implementation.\n\n# send a new nonce each time\nprint(build_auth_header(MAILBOX_ID, MAILBOX_PASSWORD))\n\n# or reuse the nonce and increment the nonce_count\nmy_nonce = str(uuid.uuid4())\n\nprint(build_auth_header(MAILBOX_ID, MAILBOX_PASSWORD, my_nonce, nonce_count=1))\nprint(build_auth_header(MAILBOX_ID, MAILBOX_PASSWORD, my_nonce, nonce_count=2))\n\n\n```\n\n## MESH API pseudocode\nTo use MESH effectively, use the following flow of API calls:\n\n- inbox poll cycle\n- outbox workflow\n\nValidate your mailbox once every 24 hours using the 'Validate a mailbox' endpoint.\n\n### Inbox poll cycle\nSpine gives each message a unique message identifier after you post it to your outbox. It is the primary identifier for the message during MESH transit.\n\nIt is suggested to poll your mailbox every 5 minutes, but at least every 24 hours. The pseudocode for a mailbox poll is:\n\n1. Poll to get the messageIds of messages ready to download from the 'Check an inbox' endpoint.\n2. For each message identifier returned in step 1:\n    * download the message with the 'Download message' endpoint\n    * if it's identified as a chunked message, download all remaining chunks with the 'Download message chunk' endpoint\n    * acknowledge receipt of the message via the 'Acknowledge message' endpoint\n3. Repeat step 2 until you have processed the number of messages returned in step 1.\n4. 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.\n\n### Asynchronous error reporting\nMost 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.\nError reports differ from regular messages in these ways:\n- the 'Download message endpoint' has a different value for the `Mex-MessageType` header:\n  * DATA for a normal organisation-to-organisation message\n  * REPORT for an error report\n- the Download message response body of an error report message is empty\n\nWe strongly recommend you check the value of `Mex-MessageType` after downloading each message, so that you can take appropriate action if needed.\n\n| Error Report Header     | Description                                                              |\n|-------------------------|--------------------------------------------------------------------------|\n| `Mex-StatusEvent`       | Step in the MESH server side process when the error occurred             |\n| `Mex-LinkedMsgID`       | The message identifier of the undelivered message                        |\n| `Mex-WorkflowID`        | The workflow identifier of the undelivered message                       |\n| `Mex-StatusTimestamp`   | Time the error occurred                                                  |\n| `Mex-LocalID`           | Sender assigned local identifier of the unacknowledged message           |\n| `Mex-StatusCode`        | Indicate the status of the message, non-00 indicates error               |\n| `Mex-MessageID`         | The message identifier of the error report (not the undelivered message) |\n| `Mex-StatusSuccess`     | SUCCESS or ERROR (is always ERROR in an error report)                    |\n| `Mex-StatusDescription` | Indicate the status the message, non-00 indicates error                  |\n| `Mex-To`                | Intended receiver of the undelivered message                             |\n| `Mex-MessageType`       | REPORT                                                                   |\n| `Mex-Subject`           | The subject of the undelivered message                                   |\n\n**Note:** Headers should be treated case insensitively, most http clients will do this for you automatically, but please do not rely on explicit case.\n\n### Error codes\nSome 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).\n\n| Error code | Typical description                                                       |\n|------------|---------------------------------------------------------------------------|\n| 02         | Data file is missing or inaccessible                                      |\n| 06         | Malformed headers                                                         |\n| 07         | Invalid From Address, the mailbox does not match the authorization header |\n| 08         | Missing Mex-To header                                                     |\n| 11         | Invalid Message Type for the transfer, should be DATA                     |\n| 12         | Unregistered to address                                                   |\n| 14         | Undelivered message                                                       |\n| 15         | Bad 'Child Protection - Information Sharing' (CP-IS) File                 |\n| 16         | Sender is not allowed to send messages of this type                       |\n| 17         | Workflow ID not registered for mailbox                                    |\n\n\n### Outbox workflow\nThe maximum amount of data allowed by MESH in a single request message is 100MB. 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 100GB (20GB if using the java client).\n\nThe [MESH UI](https://digital.nhs.uk/services/message-exchange-for-social-care-and-health-mesh/compare-mesh-services#mesh-user-interface) and older versions of the MESH client do not support chunking. Check that the receiver's interface to MESH for your workflow identifier handles chunked messages prior to sending. To do this:\n\n1. Determine the size of your message data (after compression) with a standard algorithm (such as `gzip`). If the compressed message is larger than 100MB, is smaller than 100GB, and the receiving mailbox / workflow identifier supports chunking, then you can send a chunked message. To prepare for this:\n    *  split the **uncompressed** data into ordered chunks\n    * **independently** compress each chunk with the **same** compression algorithm (such as `gzip`) such that each chunk is smaller than 100MB\n    * use the first chunk (after compression) as the initial message data\n2. Send a message with appropriate workflow identifier and `Mex-To` (recipient mailbox) header. To do this:\n    * optionally include a local identifier from step 2 for tracking.  This field must not contain PID.\n    * 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\n3. A message identifier will be returned which is the unique identifier and can be used for tracking and helping with incident resolution. It would be good practice to log this identifier.\n\n### Message expiration\nMessages 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 our [national service desk](https://digital.nhs.uk/developer/help-and-support) with the error report details and ask for the message to be placed in your inbox again.\n\n## Onboarding\n\nYou 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.\n\nYou can view a read-only version of the digital application form on the <a href=\"https://onboarding.prod.api.platform.nhs.uk/Products/PreviewOverview?apiId=34\">MESH assurance questions</a> page. \n\nTo understand how our online digital onboarding process works, see [digital onboarding](https://digital.nhs.uk/developer/guides-and-documentation/digital-onboarding). This is where you can demonstrate that you can manage risks and that your software conforms technically with the requirements for this API. You can also manage onboarding for other APIs in your account.\n\n<div class=\"nhsd-m-emphasis-box nhsd-m-emphasis-box--emphasis nhsd-!t-margin-bottom-6\" aria-label=\"Highlighted Information\">\n    <div class=\"nhsd-a-box nhsd-a-box--border-blue\">\n        <div class=\"nhsd-m-emphasis-box__image-box\">\n            <figure class=\"nhsd-a-image\">\n                <picture class=\"nhsd-a-image__picture\">\n                    <img src=\"http://digital.nhs.uk/binaries/content/gallery/icons/play-circle.svg?colour=231f20\" alt=\"\" style=\"object-fit:fill\">\n                </picture>\n            </figure>\n        </div>\n        <div class=\"nhsd-m-emphasis-box__content-box\">\n            <div data-uipath=\"website.contentblock.emphasis.content\" class=\"nhsd-t-word-break\">\n                <p class=\"nhsd-t-body\">To get started, sign in or create a <a href=\"https://onboarding.prod.api.platform.nhs.uk/\">developer account</a>, then select 'product onboarding'.</p>\n            </div>\n        </div>\n    </div>\n</div>\n\n## Contact us\nFor help and support connecting to our APIs and to join our developer community, see [Help and support building healthcare software](https://digital.nhs.uk/developer/help-and-support).","title":"Message Exchange for Social Care and Health - REST API","version":"2.0.0"},"servers":[{"description":"Integration","url":"https://msg.int.spine2.ncrs.nhs.uk"},{"description":"Integration","url":"https://msg.intspineservices.nhs.uk"},{"description":"Production","url":"https://mesh-sync.national.ncrs.nhs.uk"},{"description":"Production","url":"https://mesh-sync.spineservices.nhs.uk"}],"paths":{"/messageexchange/{mailbox_id}":{"post":{"description":"## Overview\nUse 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.\nThis 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.\n\n### Request\n\n```shell\ncurl -k \\\n--request 'GET' \\\n--cacert 'mesh-ca.pem' \\\n--key 'mesh-client-key.pem' \\\n--cert 'mesh-client-cert.pem' \\\n--header 'accept: application/vnd.mesh.v2+json' \\\n--header 'authorization: NHSMESH X26HC005:1c820cd4-be3e-43ff-807f-e65362892722:0:202006041718:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced' \\\n--header 'mex-clientversion: ApiDocs==0.0.1' \\\n--header 'mex-osarchitecture: x86_64' \\\n--header 'mex-osname: Linux' \\\n--header 'mex-osversion: #44~18.04.2-Ubuntu' \\\nhttps://mesh-sync.spineservices.nhs.uk/messageexchange/X26HC005\n```","operationId":"handshake_messageexchange__mailbox_id__post","parameters":[{"description":"mailbox identifier","example":"MAILBOX01","explode":false,"in":"path","name":"mailbox_id","required":true,"schema":{"description":"mailbox identifier","minLength":1,"title":"mailbox_id","type":"string"},"style":"simple"},{"description":"User agent string","example":"my-client;windows-10;","explode":false,"in":"header","name":"user-agent","required":false,"schema":{"default":"","description":"User agent string","title":"User-Agent","type":"string"},"style":"simple"},{"description":"Client version number","example":"ApiDocs==0.0.1","explode":false,"in":"header","name":"mex-clientversion","required":true,"schema":{"description":"Client version number","title":"mex-ClientVersion","type":"string"},"style":"simple"},{"description":"Operating system name","example":"Linux","explode":false,"in":"header","name":"mex-osname","required":true,"schema":{"description":"Operating system name","title":"mex-OSName","type":"string"},"style":"simple"},{"description":"Operating system version","example":"#44~18.04.2-Ubuntu","explode":false,"in":"header","name":"mex-osversion","required":true,"schema":{"description":"Operating system version","title":"mex-OSVersion","type":"string"},"style":"simple"},{"description":"Authorisation header","example":"authorization: NHSMESH NONFUNC01:2c001608-5f09-4840-9611-bea43e666a30:1:201511201038:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced","explode":false,"in":"header","name":"authorization","required":true,"schema":{"description":"Authorisation header","title":"Authorization","type":"string"},"style":"simple"},{"description":"the accepts header can be used to vary the response type","example":"application/vnd.mesh.v2+json","explode":false,"in":"header","name":"accept","required":false,"schema":{"default":"application/json","description":"the accepts header can be used to vary the response type","title":"Accept","type":"string"},"style":"simple"}],"responses":{"200":{"description":"Successful Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"},"403":{"description":"Authentication failed"}},"summary":"Validate a mailbox (Handshake)","tags":["Handshake"]}},"/messageexchange/{mailbox_id}/inbox":{"get":{"description":"## Overview\nUse this endpoint to return the message identifier of messages in the mailbox inbox ready for download.\nClient 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).\n\nA maximum of 500 message identifier 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.\n\n### Request\n\n```shell\ncurl -k \\\n--request 'GET' \\\n--cacert 'mesh-ca.pem' \\\n--key 'mesh-client-key.pem' \\\n--cert 'mesh-client-cert.pem' \\\n--header 'accept: application/vnd.mesh.v2+json' \\\n--header 'authorization: NHSMESH X26HC005:66eef28b-e097-421d-998d-ea0c92c2c2fb:0:202006041718:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced' \\\nhttps://mesh-sync.spineservices.nhs.uk/messageexchange/X26HC005/inbox\n```\n\n\n### Response\n\nfor `accept: application/vnd.mesh.v2+json` and later if the inbox contains more than 500 messages, then 'links.next' will provide a way to page through all the messages in the inbox\n```json\n{\n  \"messages\": [\"20220228174323222_ABCDEF\", \"20220228174323333_ABCDEF\"],\n  \"links\": {\n    \"self\": \"/messageexchange/mb12345/inbox?max_results=10\",\n    \"next\": \"/messageexchange/mb12345/inbox?max_results=10&continue_from=eyJwayI6ICJNQiNNU0cjTUIjMTIzNEhDMTIzNCMiLCAic2siOiAiTUIjTVNHIzIwMjIwMjI4MTc0MzIzMTIzX0FDREVEMSMifQ%3D%3D\"\n  }\n}\n```\nfor `accept: application/vnd.mesh.v1+json` or `accept: application/json`\n```json\n{\n  \"messages\" : [\"20200529155357895317_3573F8\", \"20220228174323333_ABCDEF\"]\n}\n```","operationId":"list_messages_messageexchange__mailbox_id__inbox_get","parameters":[{"description":"mailbox identifier","example":"MAILBOX01","explode":false,"in":"path","name":"mailbox_id","required":true,"schema":{"description":"mailbox identifier","minLength":1,"title":"mailbox_id","type":"string"},"style":"simple"},{"description":"maximum results to return when using `accept: application/vnd.mesh.v2+json` if more results exist, `links.next` will be populated","example":"100","explode":true,"in":"query","name":"max_results","required":false,"schema":{"default":500,"description":"maximum results to return when using `accept: application/vnd.mesh.v2+json` if more results exist, `links.next` will be populated","maximum":5000,"minimum":10,"title":"Max results","type":"integer"},"style":"form"},{"description":"if more results exist than `max_results`, use `continue_from` to continue retrieving results from `links.next`","examples":{"accept: application/vnd.mesh.v2+json":{"value":"eyJwayI6ICJNQiNNU0cjTUIjMTIzNEhDMTIzNCMiLCAic2siOiAiTUIjTVNHIzIwMjIwMjI4MTc0MzIzMTIzX0FDREVEMSMifQ%3D%3D"},"accept: application/json":{"value":"20220228174323123_ACDED1"}},"explode":true,"in":"query","name":"continue_from","required":false,"schema":{"description":"if more results exist than `max_results`, use `continue_from` to continue retrieving results from `links.next`","maxLength":1000,"minLength":24,"title":"Continue From","type":"string"},"style":"form"},{"description":"filter inbox by workflow id, conditions:\n* equals: =WORKFLOW1\n* does not equal: =!WORKFLOW1\n* begins with: =WORKFL\\*\n* does not begin with: =!WORKFL\\*\n* contains: =\\*_ACK\\*\n* does not contain: =!\\*_ACK\\*","example":"!*_ACK*","explode":true,"in":"query","name":"workflow_filter","required":false,"schema":{"description":"filter inbox by workflow id, conditions:\n* equals: =WORKFLOW1\n* does not equal: =!WORKFLOW1\n* begins with: =WORKFL\\*\n* does not begin with: =!WORKFL\\*\n* contains: =\\*_ACK\\*\n* does not contain: =!\\*_ACK\\*","maxLength":255,"minLength":2,"title":"Workflow Id filter","type":"string"},"style":"form"},{"description":"Authorisation header","example":"authorization: NHSMESH NONFUNC01:2c001608-5f09-4840-9611-bea43e666a30:1:201511201038:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced","explode":false,"in":"header","name":"authorization","required":true,"schema":{"description":"Authorisation header","title":"Authorization","type":"string"},"style":"simple"},{"description":"the accepts header can be used to vary the response type","example":"application/vnd.mesh.v2+json","explode":false,"in":"header","name":"accept","required":false,"schema":{"default":"application/json","description":"the accepts header can be used to vary the response type","title":"Accept","type":"string"},"style":"simple"}],"responses":{"200":{"content":{"application/vnd.mesh.v2+json":{"schema":{"$ref":"#/components/schemas/Inbox"}},"application/json":{"schema":{"$ref":"#/components/schemas/Inbox_1"}}},"description":"Successful Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"},"403":{"description":"Authentication failed"}},"summary":"Check an inbox","tags":["Inbox"]}},"/messageexchange/{mailbox_id}/inbox/{message_id}":{"get":{"description":"## Overview\nUse this endpoint to retrieve a message based on the message identifier obtained from the 'Check Inbox' endpoint.\n\n**Note:** Headers should be treated case insensitively, most http clients will do this for you automatically, but please do not rely on explicit case.\n\n### Message expiration\nMessages 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](https://digital.nhs.uk/developer/help-and-support) with the error report details and ask for the message to be re-sent.\n\n### Report Messages\nThe `Mex-MessageType` header indicates if the payload is a `DATA` message or a `REPORT`.\nError reports differ from regular messages in these ways:\n- the Download message endpoint has a different value for the Mex-MessageType header\n  * DATA for a normal organisation-to-organisation message\n  * REPORT for an error report\n- the Download message response body of an error report message is empty\n\n### Request\n\n```shell\n  curl -k \\\n  --request 'GET' \\\n  --cacert 'mesh-ca.pem' \\\n  --key 'mesh-client-key.pem' \\\n  --cert 'mesh-client-cert.pem' \\\n  --header 'accept: application/vnd.mesh.v2+json' \\\n  --header 'authorization: NHSMESH X26HC005:2942264f-46e5-450f-90fc-22a0c09efa37:0:202006041718:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced' \\\n  https://msg.int.spine2.ncrs.nhs.uk/messageexchange/X26HC005/inbox/20200529155357895317_3573F8\n```\n\n### Response\n\n```shell\nHTTP/1.1 200 OK\ncontent-type: application/octet-stream\ncontent-length: 27\nmex-content-compressed: N\nmex-addresstype: ALL\nmex-localid: api-docs-bob-sends-alice-a-chunked-file\nmex-chunk-range: 2:2\netag: \"866243ab74e0107a4d5835f8d6552e7f20c39ee1\"\nmex-filename: message.txt.gz\nmex-version: 1.0\nmex-workflowid: API-DOCS-TEST\nmex-to: X26HC005\nmex-messagetype: DATA\nmex-messageid: 20200601122152994285_D59900\nmex-from: X26HC006\n\nm you in the future,\n\nBob.\n```","operationId":"retrieve_message_messageexchange__mailbox_id__inbox__message_id__get","parameters":[{"description":"mailbox identifier","example":"MAILBOX01","explode":false,"in":"path","name":"mailbox_id","required":true,"schema":{"description":"mailbox identifier","minLength":1,"title":"mailbox_id","type":"string"},"style":"simple"},{"description":"message identifier","example":"20210311101813838554_1B8F53","explode":false,"in":"path","name":"message_id","required":true,"schema":{"description":"message identifier","minLength":1,"title":"message_id","type":"string"},"style":"simple"},{"description":"client accepted content encoding(s)","example":"gzip","explode":false,"in":"header","name":"accept-encoding","required":false,"schema":{"default":"","description":"client accepted content encoding(s)","title":"Accept-Encoding","type":"string"},"style":"simple"},{"description":"Authorisation header","example":"authorization: NHSMESH NONFUNC01:2c001608-5f09-4840-9611-bea43e666a30:1:201511201038:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced","explode":false,"in":"header","name":"authorization","required":true,"schema":{"description":"Authorisation header","title":"Authorization","type":"string"},"style":"simple"}],"responses":{"200":{"content":{"application/octet-stream":{"schema":{"format":"binary"}}},"description":"OK, full message retrieved"},"206":{"content":{"application/octet-stream":{"schema":{"format":"binary"}}},"description":"Partial Content - Indicates that chunk has been downloaded successfully and that there are further chunks."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"},"403":{"description":"Authentication failed"},"404":{"description":"Not Found, message does not exist"},"410":{"description":"Gone, message has expired or otherwise failed"}},"summary":"Get Message","tags":["Inbox"]},"head":{"description":"## Overview\nUse this endpoint to retrieve a message metadata based on the `message_id` obtained from the 'Check Inbox' endpoint.\n\n### Message expiration\nMessages 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](https://digital.nhs.uk/developer/help-and-support) with the error report details and ask for the message to be re-sent.\n\n### Report Messages\nThe `Mex-MessageType` header indicates if the payload is a `DATA` message or a `REPORT`.\nError reports differ from regular messages in these ways:\n- the Download message endpoint has a different value for the `Mex-MessageType` header\n  * DATA for a normal organisation-to-organisation message\n  * REPORT for an error report\n\n**Note:** Headers should be treated case insensitively, most http clients will do this for you automatically, but please do not rely on explicit case.\n\n### Request\n\n```shell\n  curl -k \\\n  --request 'HEAD' \\\n  --cacert 'mesh-ca.pem' \\\n  --key 'mesh-client-key.pem' \\\n  --cert 'mesh-client-cert.pem' \\\n  --header 'accept: application/vnd.mesh.v2+json' \\\n  --header 'authorization: NHSMESH X26HC005:2942264f-46e5-450f-90fc-22a0c09efa37:0:202006041718:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced' \\\n  https://msg.int.spine2.ncrs.nhs.uk/messageexchange/{mailbox_id}/inbox/{message_id}\n```\n\n### Response\n\n```shell\nHTTP/1.1 200 OK\ncontent-type: application/vnd.mesh.v2+json\ncontent-length: 0\nmex-content-compressed: N\nmex-addresstype: ALL\nmex-localid: api-docs-bob-sends-alice-a-chunked-file\nmex-chunk-range: 2:2\netag: \"866243ab74e0107a4d5835f8d6552e7f20c39ee1\"\nmex-filename: message.txt.gz\nmex-version: 1.0\nmex-workflowid: API-DOCS-TEST\nmex-to: X26HC005\nmex-messagetype: DATA\nmex-messageid: 20200601122152994285_D59900\nmex-from: X26HC006\n```","operationId":"head_message_messageexchange__mailbox_id__inbox__message_id__head","parameters":[{"description":"mailbox identifier","example":"MAILBOX01","explode":false,"in":"path","name":"mailbox_id","required":true,"schema":{"description":"mailbox identifier","minLength":1,"title":"mailbox_id","type":"string"},"style":"simple"},{"description":"message identifier","example":"20210311101813838554_1B8F53","explode":false,"in":"path","name":"message_id","required":true,"schema":{"description":"message identifier","minLength":1,"title":"message_id","type":"string"},"style":"simple"},{"description":"Authorisation header","example":"authorization: NHSMESH NONFUNC01:2c001608-5f09-4840-9611-bea43e666a30:1:201511201038:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced","explode":false,"in":"header","name":"authorization","required":true,"schema":{"description":"Authorisation header","title":"Authorization","type":"string"},"style":"simple"}],"responses":{"200":{"description":"Successful Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"},"403":{"description":"Authentication failed"},"404":{"description":"Not Found, message does not exist"},"410":{"description":"Gone, message has expired or otherwise failed"}},"summary":"Head Message","tags":["Inbox"]}},"/messageexchange/{mailbox_id}/inbox/{message_id}/status/acknowledged":{"put":{"description":"## Overview\nUse this endpoint to acknowledge the successful download of a message.\n\nThis operation:\n\n* closes the message transaction on Spine\n* removes the message from your mailbox inbox, which means that the `message_id` does not appear in subsequent calls to the 'Check inbox' endpoint and cannot be downloaded again\n\n**Note:** If you fail to acknowledge a message after five days in the inbox this sends a non-delivery report to the sender's inbox.\n\n### Request\n\n```shell\ncurl -k \\\n--request 'PUT' \\\n--cacert 'mesh-ca.pem' \\\n--key 'mesh-client-key.pem' \\\n--cert 'mesh-client-cert.pem' \\\n--header 'accept: application/vnd.mesh.v2+json' \\\n--header 'authorization: NHSMESH X26HC005:bb59be38-e50b-4e5a-9f11-e566e7509552:0:202006041718:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced' \\\nhttps://mesh-sync.spineservices.nhs.uk/messageexchange/X26HC005/inbox/20200529155357895317_3573F8/status/acknowledged\n```\n\n### Response\n\nfor `accept: application/vnd.mesh.v2+json` no response body will be returned\n\nfor `accept: application/vnd.mesh.v1+json` or `accept: application/json`\n```json\n{ \"messageId\" : \"20200529155357895317_3573F8\" }\n```","operationId":"acknowledge_message_messageexchange__mailbox_id__inbox__message_id__status_acknowledged_put","parameters":[{"description":"mailbox identifier","example":"MAILBOX01","explode":false,"in":"path","name":"mailbox_id","required":true,"schema":{"description":"mailbox identifier","minLength":1,"title":"mailbox_id","type":"string"},"style":"simple"},{"description":"message identifier","example":"20210311101813838554_1B8F53","explode":false,"in":"path","name":"message_id","required":true,"schema":{"description":"message identifier","minLength":1,"title":"message_id","type":"string"},"style":"simple"},{"description":"Authorisation header","example":"authorization: NHSMESH NONFUNC01:2c001608-5f09-4840-9611-bea43e666a30:1:201511201038:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced","explode":false,"in":"header","name":"authorization","required":true,"schema":{"description":"Authorisation header","title":"Authorization","type":"string"},"style":"simple"},{"description":"the accepts header can be used to vary the response type","example":"application/vnd.mesh.v2+json","explode":false,"in":"header","name":"accept","required":false,"schema":{"default":"application/json","description":"the accepts header can be used to vary the response type","title":"Accept","type":"string"},"style":"simple"}],"responses":{"200":{"description":"Successful Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"},"403":{"description":"Authentication failed"}},"summary":"Acknowledge message","tags":["Inbox"]}},"/messageexchange/{mailbox_id}/inbox/{message_id}/{chunk_number}":{"get":{"description":"Use this endpoint to download a chunked message. Initially, call the 'Download Message' endpoint with the message identifier given by the 'Check Inbox' endpoint as usual. When the message is chunked, the 'Download message' endpoint response differs in two ways:\n* the response code is '206: Partial Content' (instead of '200: OK')\n* the response headers contain Mex-Chunk-Range: 1:n\n\n\nThis endpoint is used to download the remaining n-1 chunks.\n\n**Note:** Headers should be treated case insensitively, most http clients will do this for you automatically, but please do not rely on explicit case.\n\n### Request\n\nFollowing on from the example in the 'Send chunked message' endpoint, Alice checks her inbox and sees a new message.\n\n\n```shell\ncurl -k \\\n--cacert 'mesh-ca.pem' \\\n--key 'mesh-client-key.pem' \\\n--cert 'mesh-client-cert.pem' \\\n--request 'GET' \\\n--header 'accept: application/vnd.mesh.v2+json' \\\n--header 'authorization: NHSMESH X26HC005:142b8a1e-e953-4e5e-98a8-b27741e15747:0:202006041718:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced' \\\nhttps://mesh-sync.spineservices.nhs.uk/messageexchange/X26HC005/inbox\n```\n\nShe 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.\n\n```shell\ncurl -k \\\n--include \\\n--request 'GET' \\\n--cacert 'mesh-ca.pem' \\\n--key 'mesh-client-key.pem' \\\n--cert 'mesh-client-cert.pem' \\\n--header 'accept: application/vnd.mesh.v2+json' \\\n--header 'authorization: NHSMESH X26HC005:777670ce-02f7-44fe-a53b-eb33eb1cb564:0:202006041718:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced' \\\nhttps://mesh-sync.spineservices.nhs.uk/messageexchange/X26HC005/inbox/20200601122152994285_D59900\n```\n\n```shell\nHTTP/1.1 206 Partial Content\ncontent-type: application/octet-stream\ncontent-length: 100\nmex-chunk-range: 1:2\nmex-workflowid: API-DOCS-TEST\nmex-content-compressed: N\nmex-addresstype: ALL\nmex-statussuccess: SUCCESS\nmex-statusdescription: Transferred to recipient mailbox\nnex-messagetype: DATA\nmex-statusevent: TRANSFER\nmex-to: X26HC005\nmex-statustimestamp: 20200601122152\nmex-localid: api-docs-bob-sends-alice-a-chunked-file\nmex-statuscode: 00\nmex-filename: message.txt.gz\nmex-messageid: 20200601122152994285_D59900\nmex-from: X26HC006\n\nHi Alice,\n\nThis is Bob. It's really nice that we can communicate via SPINE!\n\nI hope to hear more fro\n```\n\nHere 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).\n\nAlice 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.\n\nAlice makes another call to retrieve the second part of the message.\n\n```shell\ncurl -k \\\n--include \\\n--cacert 'mesh-ca.pem' \\\n--key 'mesh-client-key.pem' \\\n--cert 'mesh-client-cert.pem' \\\n--header 'accept: application/vnd.mesh.v2+json' \\\n--header 'authorization: NHSMESH X26HC005:71139532-9215-4ff8-8a74-d602386bac30:0:202006041718:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced' \\\nhttps://mesh-sync.spineservices.nhs.uk/messageexchange/X26HC005/inbox/20200601122152994285_D59900/2 | tr -d '\\r'\n```\n\n```shell\nHTTP/1.1 200 OK\ncontent-type: application/octet-stream\ncontent-length: 27\nmex-content-compressed: N\nmex-addresstype: ALL\nmex-localid: api-docs-bob-sends-alice-a-chunked-file\nmex-chunk-range: 2:2\netag: \"866243ab74e0107a4d5835f8d6552e7f20c39ee1\"\nmex-filename: message.txt.gz\nmex-version: 1.0\nmex-workflowid: API-DOCS-TEST\nmex-to: X26HC005\nmex-messagetype: DATA\nmex-messageid: 20200601122152994285_D59900\nmex-from: X26HC006\n\nm you in the future,\n\nBob.\n```\n\nThat this is the final part of the message is indicated in two ways:\n\n-   the response code is `200 OK` rather than `206 Partial Content`\n-   the `Mex-Chunk-Range` response header is `2:2`","operationId":"retrieve_chunk_messageexchange__mailbox_id__inbox__message_id___chunk_number__get","parameters":[{"description":"The index number of the chunk","example":"1","explode":false,"in":"path","name":"chunk_number","required":true,"schema":{"description":"The index number of the chunk","minimum":1,"title":"chunk_number","type":"integer"},"style":"simple"},{"description":"mailbox identifier","example":"MAILBOX01","explode":false,"in":"path","name":"mailbox_id","required":true,"schema":{"description":"mailbox identifier","minLength":1,"title":"mailbox_id","type":"string"},"style":"simple"},{"description":"message identifier","example":"20210311101813838554_1B8F53","explode":false,"in":"path","name":"message_id","required":true,"schema":{"description":"message identifier","minLength":1,"title":"message_id","type":"string"},"style":"simple"},{"description":"client accepted content encoding(s)","example":"gzip","explode":false,"in":"header","name":"accept-encoding","required":false,"schema":{"default":"","description":"client accepted content encoding(s)","title":"Accept-Encoding","type":"string"},"style":"simple"},{"description":"Authorisation header","example":"authorization: NHSMESH NONFUNC01:2c001608-5f09-4840-9611-bea43e666a30:1:201511201038:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced","explode":false,"in":"header","name":"authorization","required":true,"schema":{"description":"Authorisation header","title":"Authorization","type":"string"},"style":"simple"}],"responses":{"200":{"content":{"application/octet-stream":{"schema":{"format":"binary"}}},"description":"OK - chunk downloaded and no further chunks exist"},"206":{"content":{"application/octet-stream":{"schema":{"format":"binary"}}},"description":"Partial Content - Indicates that chunk has been downloaded successfully and that there are further chunks."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"},"403":{"description":"Authentication failed"},"404":{"description":"Not Found, message does not exist"},"410":{"description":"Gone, message has expired or otherwise failed"}},"summary":"Get Message chunk","tags":["Inbox"]}},"/messageexchange/{mailbox_id}/count":{"get":{"deprecated":true,"description":"## Overview\nUse this endpoint to check the number of messages currently held in the MESH mailbox that are ready to download.\n\nThis endpoint is now deprecated as it is not needed as part of the polling cycle.","operationId":"count_messages_in_inbox_messageexchange__mailbox_id__count_get","parameters":[{"description":"mailbox identifier","example":"MAILBOX01","explode":false,"in":"path","name":"mailbox_id","required":true,"schema":{"description":"mailbox identifier","minLength":1,"title":"mailbox_id","type":"string"},"style":"simple"},{"description":"Authorisation header","example":"authorization: NHSMESH NONFUNC01:2c001608-5f09-4840-9611-bea43e666a30:1:201511201038:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced","explode":false,"in":"header","name":"authorization","required":true,"schema":{"description":"Authorisation header","title":"Authorization","type":"string"},"style":"simple"}],"responses":{"200":{"content":{"application/vnd.mesh.v2+json":{"schema":{"$ref":"#/components/schemas/InboxCount"}},"application/json":{"schema":{"$ref":"#/components/schemas/InboxCount_1"}}},"description":"Successful Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"},"403":{"description":"Forbidden"}},"summary":"Check an inbox count (deprecated)","tags":["Inbox"]}},"/messageexchange/{mailbox_id}/outbox":{"post":{"description":"## Overview\nUse 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.\n\n### Messages larger than 100MB\nThe largest data payload the MESH API accepts in a single request is 100MB. 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:\n  1.  The total compressed size of the message is < 100MB - this is the Spine upper limit for a single message.\n  2.  The receiver mailbox and workflow identifier support the downloading of chunked messages. MESH UI and older versions of the MESH client do not support this.\n\nTo correctly break the outbound message into valid chunks:\n  1.  Split the **uncompressed** message into `n` ordered chunks such that each (compressed) chunk is smaller than 100MB.\n  2.  **Independently** compress each chunk with the same compression algorithm (e.g. `gzip`).\n  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 message identifier of this initial server response **must** be captured as it is a required path element of the Send chunked message URL.\n\nAlways set the workflow identifier as some workflows are restricted which means the mailbox sender and recipient must be configured for the workflow identifier you send.\n\nTo discover the recipient mailbox either use the `endpointlookup` endpoint or for certain workflows you can include [demographic details](https://digital.nhs.uk/services/message-exchange-for-social-care-and-health-mesh/mesh-guidance-hub/endpoint-lookup-service-and-workflowids#using-the-to_dts-field-of-a-mesh-message-to-find-a-mailbox-) in the `Mex-To` field.\n\nIt is good practice to capture the returned message identifier as this provides a unique identifier which you can use for message tracking.\n\n### Request\n\n```shell\ncurl -k \\\n--request 'POST' \\\n--cacert 'mesh-ca.pem' \\\n--key 'mesh-client-key.pem' \\\n--cert 'mesh-client-cert.pem' \\\n--header 'accept: application/vnd.mesh.v2+json' \\\n--header 'authorization: NHSMESH X26HC006:c1f2df9c-fe9e-4d11-ba78-49a8bc705eb4:0:202006041718:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced' \\\n--header 'content-type: application/octet-stream' \\\n--header 'mex-from: X26HC006' \\\n--header 'mex-to: X26HC005' \\\n--header 'mex-workflowid: API-DOCS-TEST' \\\n--header 'mex-filename: None' \\\n--header 'mex-localid: api-docs-bob-greets-alice' \\\n--data 'This is a message' \\\nhttps://mesh-sync.spineservices.nhs.uk/messageexchange/X26HC006/outbox\n```\n\n### Response\n\nfor `accept: application/vnd.mesh.v2+json`\n```json\n{\"message_id\": \"20200529155357895317_3573F8\"}\n```\nfor `accept: application/vnd.mesh.v1+json` or `accept: application/json`\n```json\n{\"messageID\": \"20200529155357895317_3573F8\"}\n```","operationId":"send_message","parameters":[{"description":"mailbox identifier","example":"MAILBOX01","explode":false,"in":"path","name":"mailbox_id","required":true,"schema":{"description":"mailbox identifier","minLength":1,"title":"mailbox_id","type":"string"},"style":"simple"},{"description":"Authorisation header","example":"authorization: NHSMESH NONFUNC01:2c001608-5f09-4840-9611-bea43e666a30:1:201511201038:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced","explode":false,"in":"header","name":"authorization","required":true,"schema":{"description":"Authorisation header","title":"Authorization","type":"string"},"style":"simple"},{"description":"Recipient mailbox ID","example":"MAILBOX01","explode":false,"in":"header","name":"mex-to","required":true,"schema":{"default":"","description":"Recipient mailbox ID","maxLength":100,"title":"mex-To","type":"string"},"style":"simple"},{"description":"Identifies the type of message being sent e.g. Pathology, GP Capitation.","explode":false,"in":"header","name":"mex-workflowid","required":true,"schema":{"default":"","description":"Identifies the type of message being sent e.g. Pathology, GP Capitation.","maxLength":300,"title":"mex-WorkflowID","type":"string"},"style":"simple"},{"description":"chunk range","example":"1:2","explode":false,"in":"header","name":"mex-chunk-range","required":false,"schema":{"default":"","description":"chunk range","maxLength":20,"title":"mex-Chunk-Range","type":"string"},"style":"simple"},{"description":"additional message subject","explode":false,"in":"header","name":"mex-subject","required":false,"schema":{"default":"","description":"additional message subject","maxLength":500,"title":"mex-Subject","type":"string"},"style":"simple"},{"description":"local identifier, your reference","explode":false,"in":"header","name":"mex-localid","required":false,"schema":{"default":"","description":"local identifier, your reference","maxLength":300,"title":"mex-LocalID","type":"string"},"style":"simple"},{"description":"local filename","explode":false,"in":"header","name":"mex-filename","required":false,"schema":{"default":"","description":"local filename","maxLength":300,"title":"mex-FileName","type":"string"},"style":"simple"},{"description":"Checksum of the original message contents, as provided by the message sender","example":"b10a8db164e0754105b7a99be72e3fe5","explode":false,"in":"header","name":"mex-content-checksum","required":false,"schema":{"default":"","description":"Checksum of the original message contents, as provided by the message sender","maxLength":100,"title":"mex-Content-Checksum","type":"string"},"style":"simple"},{"description":"content type of the message when decoded","example":"text/csv","explode":false,"in":"header","name":"content-type","required":false,"schema":{"default":"","description":"content type of the message when decoded","title":"Content-Type","type":"string"},"style":"simple"},{"description":"content encoding","example":"gzip","explode":false,"in":"header","name":"content-encoding","required":false,"schema":{"default":"","description":"content encoding","title":"Content-Encoding","type":"string"},"style":"simple"},{"description":"the accepts header can be used to vary the response type","example":"application/vnd.mesh.v2+json","explode":false,"in":"header","name":"accept","required":false,"schema":{"default":"application/json","description":"the accepts header can be used to vary the response type","title":"Accept","type":"string"},"style":"simple"}],"requestBody":{"content":{"application/octet-stream":{"example":"... message payload bytes...","schema":{"format":"binary"}},"*/*":{"example":"message content....\n                        any content type is acceptable but use application/octet-stream if you want a single default","schema":{"format":"any"}}},"description":"message payload or chunk, optionally encoded with content-encoding","required":true},"responses":{"202":{"content":{"application/vnd.mesh.v2+json":{"schema":{"$ref":"#/components/schemas/SendMessage"}},"application/json":{"schema":{"$ref":"#/components/schemas/SendMessage_1"}}},"description":"Successful Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"},"403":{"description":"Forbidden"},"417":{"content":{"application/vnd.mesh.v2+json":{"schema":{"$ref":"#/components/schemas/MeshError"}},"application/json":{"schema":{"$ref":"#/components/schemas/MeshError_1"}}},"description":"Expectation Failed"}},"summary":"Send message","tags":["Outbox"]}},"/messageexchange/{mailbox_id}/outbox/{message_id}/{chunk_number}":{"post":{"description":"## Overview\nUse this endpoint to send a chunked message. The 'Send Message' endpoint has a maximum single request message payload size of 100MB. However, you can send much larger messages (up to 20GB) by breaking up the message into chunks and transmitting it over multiple requests.\n\n**Note**: Some workflow ids 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.\n\nTo send a chunked message:\n\n1. Split it into separate files\n2. Compress the individual chunks **separately** with the **same** compression program (e.g. `gzip`).\n   - **DO NOT** compress a large file and then split the compressed version\n3. Upload the first file using the normal 'Send message' endpoint.\n   - 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\n   - capture the message identifier field in the returned JSON\n4. Upload subsequent files in the correct order using the chunked message endpoint\n\n**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.\n\n### Request\n\nSuppose 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.\n```shell\nls -sh message.txt\n4.0kb message.txt\n```\n```shell\ncat message.txt\n\nHi Alice,\n\nThis is Bob. It's really nice that we can communicate via SPINE!\n\nI hope to hear more from you in the future,\n\nBob.\n```\n\n  First we break up our one \"large\" file into two smaller files. We will transmit one per request.\n\n```shell\nsplit -b 100 message.txt message.txt_\nls -sh message.txt_*\n```\n\nLarge messages should be compressed to reduce the bandwidth and storage requirements for Spine.\n```shell\nfor chunk_file in message.txt_*; do\n  gzip -k -f $chunk_file;\ndone\nls -sh message.txt_*.gz\n\n4.0kb message.txt_aa.gz\n4.0kb message.txt_ab.gz\n```\n```shell\ncurl -k \\\n--cacert 'mesh-ca.pem' \\\n--key 'mesh-client-key.pem' \\\n--cert 'mesh-client-cert.pem' \\\n--request 'POST' \\\n--header 'accept: application/vnd.mesh.v2+json' \\\n--header 'authorization: NHSMESH X26HC006:2c6e938e-9a72-4a7a-9664-96ac1f341331:0:202006041718:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced' \\\n--header 'content-type: application/octet-stream' \\\n--header 'mex-from: X26HC006' \\\n--header 'mex-to: X26HC005' \\\n--header 'mex-workflowid: API-DOCS-TEST' \\\n--header 'mex-filename: message.txt.gz' \\\n--header 'mex-localid: api-docs-bob-sends-alice-a-chunked-file' \\\n--header 'mex-chunk-range: 1:2' \\\n--header 'content-encoding: gzip' \\\n--data-binary '@message.txt_aa.gz' \\\nhttps://mesh-sync.spineservices.nhs.uk/messageexchange/X26HC006/outbox\n```\n```shell\ncurl -k \\\n--cacert 'mesh-ca.pem' \\\n--key 'mesh-client-key.pem' \\\n--cert 'mesh-client-cert.pem' \\\n--request 'POST' \\\n--header 'accept: application/vnd.mesh.v2+json' \\\n--header 'authorization: NHSMESH X26HC006:06bf0527-ba77-47f0-b22f-d7d08a88ad26:0:202006041718:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced' \\\n--header 'mex-chunk-range: 2:2' \\\n--data-binary '@./message.txt_ab.gz' \\\nhttps://mesh-sync.spineservices.nhs.uk/messageexchange/X26HC006/outbox/20200601122152994285_D59900/2\n```","operationId":"send_chunk","parameters":[{"description":"The index number of the chunk","example":"1","explode":false,"in":"path","name":"chunk_number","required":true,"schema":{"description":"The index number of the chunk","title":"chunk_number","type":"integer"},"style":"simple"},{"description":"mailbox identifier","example":"MAILBOX01","explode":false,"in":"path","name":"mailbox_id","required":true,"schema":{"description":"mailbox identifier","minLength":1,"title":"mailbox_id","type":"string"},"style":"simple"},{"description":"message identifier","example":"20210311101813838554_1B8F53","explode":false,"in":"path","name":"message_id","required":true,"schema":{"description":"message identifier","minLength":1,"title":"message_id","type":"string"},"style":"simple"},{"description":"chunk range for the current chunk","example":"2:3","explode":false,"in":"header","name":"mex-chunk-range","required":false,"schema":{"default":"","description":"chunk range for the current chunk","maxLength":20,"title":"mex-Chunk-Range","type":"string"},"style":"simple"},{"description":"Authorisation header","example":"authorization: NHSMESH NONFUNC01:2c001608-5f09-4840-9611-bea43e666a30:1:201511201038:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced","explode":false,"in":"header","name":"authorization","required":true,"schema":{"description":"Authorisation header","title":"Authorization","type":"string"},"style":"simple"},{"description":"content encoding","example":"gzip","explode":false,"in":"header","name":"content-encoding","required":false,"schema":{"default":"","description":"content encoding","title":"Content-Encoding","type":"string"},"style":"simple"},{"description":"the accepts header can be used to vary the response type","example":"application/vnd.mesh.v2+json","explode":false,"in":"header","name":"accept","required":false,"schema":{"default":"application/json","description":"the accepts header can be used to vary the response type","title":"Accept","type":"string"},"style":"simple"}],"requestBody":{"content":{"application/octet-stream":{"example":"... message payload bytes...","schema":{"format":"binary"}},"*/*":{"example":"message content....\n                        any content type is acceptable but use application/octet-stream if you want a single default","schema":{"format":"any"}}},"description":"message payload or chunk, optionally encoded with content-encoding","required":true},"responses":{"202":{"content":{"application/vnd.mesh.v2+json":{"schema":{"$ref":"#/components/schemas/SendMessage"}},"application/json":{"schema":{"$ref":"#/components/schemas/SendMessage_1"}}},"description":"Successful Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"},"403":{"description":"Forbidden"},"404":{"description":"Not Found, message does not exist"},"417":{"content":{"application/vnd.mesh.v2+json":{"schema":{"$ref":"#/components/schemas/MeshError"}},"application/json":{"schema":{"$ref":"#/components/schemas/MeshError_1"}}},"description":"Expectation Failed"},"423":{"description":"Messages has been finalised; no more chunks can be uploaded"}},"summary":"Send chunked message","tags":["Outbox"]}},"/messageexchange/{mailbox_id}/outbox/tracking":{"get":{"description":"## Overview\nUse 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.\n\nThe message identifier is the value returned in the response to a message upload.\n\nDo 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 workflow identifier appended with `_ACK`.\n\n### Request\nIt 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).\n\n\n```shell\ncurl -k \\\n--cacert 'mesh-ca.pem' \\\n--key 'mesh-client-key.pem' \\\n--cert 'mesh-client-cert.pem' \\\n--header 'accept: application/vnd.mesh.v2+json' \\\n--header 'authorization: NHSMESH X26HC006:1f6c9442-eb9a-440c-b4ed-ee4fd525e176:0:202006041718:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced' \\\nhttps://mesh-sync.spineservices.nhs.uk/messageexchange/X26HC006/outbox/tracking?messageID=20210311101813838554_1B8F53\n```\n\n### Response\n\nfor `accept: application/vnd.mesh.v2+json`\n\n```json\n{\n  \"message_id\": \"20210311101813838554_1B8F53\",\n  \"local_id\": \"api-docs-bob-sends-alice-a-chunked-file\",\n  \"workflow_id\": \"API-DOCS-TEST\",\n  \"filename\": \"message.txt.gz\",\n  \"expiry_time\": \"20200606122153\",\n  \"upload_timestamp\": \"20200601122152\",\n  \"recipient\": \"X26HC005\",\n  \"recipient_name\": \"APIM bebop\",\n  \"recipient_ods_code\": \"X26\",\n  \"recipient_org_code\": \"TestOrg\",\n  \"recipient_org_name\": \"TEST Org Partnership Trust\",\n  \"status_success\": true,\n  \"status\": \"accepted\",\n  \"status_event\": \"TRANSFER\",\n  \"status_timestamp\": \"2020-06-01T12:21:52\",\n  \"status_description\": \"Success\",\n  \"status_code\": \"01\"\n}\n```\nfor `accept: application/vnd.mesh.v1+json` or `accept: application/json`\n\n```json\n{\n  \"addressType\": \"ALL\",\n  \"checksum\": null,\n  \"compressFlag\": null,\n  \"contentEncoding\": \"gzip\",\n  \"contentsBase64\": true,\n  \"dtsId\": \"20210311101813838554_1B8F53\",\n  \"encryptedFlag\": null,\n  \"expiryTime\": \"20200606122153\",\n  \"fileName\": \"message.txt.gz\",\n  \"fileSize\": 187,\n  \"isCompressed\": null,\n  \"localId\": \"api-docs-bob-sends-alice-a-chunked-file\",\n  \"meshRecipientOdsCode\": \"X26\",\n  \"messageId\": \"20210311101813838554_1B8F53\",\n  \"messageType\": \"DATA\",\n  \"partnerId\": null,\n  \"processId\": null,\n  \"recipient\": \"X26HC005\",\n  \"recipientBillingEntity\": \"England\",\n  \"recipientName\": \"APIM bebop\",\n  \"recipientOrgCode\": \"TestOrg\",\n  \"recipientOrgName\": \"TEST Org Partnership Trust\",\n  \"recipientSmtp\": \"x26hc005@dts.nhs.uk\",\n  \"sender\": \"X26HC006\",\n  \"senderBillingEntity\": \"England\",\n  \"senderName\": \"APIM bebop\",\n  \"senderOdsCode\": \"X26\",\n  \"senderOrgCode\": \"TestOrg\",\n  \"senderOrgName\": \"TEST Org Partnership Trust\",\n  \"senderSmtp\": \"x26hc006@dts.nhs.uk\",\n  \"status\": \"Accepted\",\n  \"statusCode\": null,\n  \"statusDescription\": null,\n  \"statusEvent\": null,\n  \"statusSuccess\": null,\n  \"statusTimestamp\": null,\n  \"subject\": null,\n  \"uploadTimestamp\": \"20200601122152\",\n  \"version\": \"1.0\",\n  \"workflowId\": \"API-DOCS-TEST\"\n}\n```\n\nSuppose Alice only now acknowledges the message Bob sent.\n\n### Request\n\n```shell\ncurl -k \\\n--request 'PUT' \\\n--cacert 'mesh-ca.pem' \\\n--key 'mesh-client-key.pem' \\\n--cert 'mesh-client-cert.pem' \\\n--header 'accept: application/vnd.mesh.v2+json' \\\n--header 'authorization: NHSMESH X26HC005:57db9dd2-2156-4c02-90d4-66e7082179db:0:202006041718:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced' \\\nhttps://mesh-sync.spineservices.nhs.uk/messageexchange/X26HC005/inbox/20210311101813838554_1B8F53/status/acknowledged\n```\n\n### Response\n\n```json\n{\"message_id\" : \"20210311101813838554_1B8F53\" }\n```\n\nThe next call to Track outbox by Bob\n\n### Request\n\n```shell\ncurl -k \\\n--cacert 'mesh-ca.pem' \\\n--key 'mesh-client-key.pem' \\\n--cert 'mesh-client-cert.pem' \\\n--header 'accept: application/vnd.mesh.v2+json' \\\n--header 'authorization: NHSMESH X26HC006:dd3f8609-b2c3-4f5a-aa62-c456579b8f77:0:202006041718:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced' \\\nhttps://mesh-sync.spineservices.nhs.uk/messageexchange/X26HC006/outbox/tracking?messageID=20210311101813838554_1B8F53\n```\n\n### Response\n\n```json\n{\n  \"status_timestamp\": \"2020-06-01T12:21:52\",\n  \"status\": \"acknowledged\",\n  \"message_id\": \"20210311101813838554_1B8F53\"\n}\n```\n\nThis shows the `status` field of the response has changed from `Accepted` to `Acknowledged`.  All the fields in the previous response are also included.","operationId":"tracking_by_message_id_messageexchange__mailbox_id__outbox_tracking_get","parameters":[{"description":"mailbox identifier","example":"MAILBOX01","explode":false,"in":"path","name":"mailbox_id","required":true,"schema":{"description":"mailbox identifier","minLength":1,"title":"mailbox_id","type":"string"},"style":"simple"},{"description":"message identifier","example":"20210311101813838554_1B8F53","explode":true,"in":"query","name":"messageID","required":true,"schema":{"description":"message identifier","minLength":1,"title":"message identifier","type":"string"},"style":"form"},{"description":"Authorisation header","example":"authorization: NHSMESH NONFUNC01:2c001608-5f09-4840-9611-bea43e666a30:1:201511201038:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced","explode":false,"in":"header","name":"authorization","required":true,"schema":{"description":"Authorisation header","title":"Authorization","type":"string"},"style":"simple"},{"description":"the accepts header can be used to vary the response type","example":"application/vnd.mesh.v2+json","explode":false,"in":"header","name":"accept","required":false,"schema":{"default":"application/json","description":"the accepts header can be used to vary the response type","title":"Accept","type":"string"},"style":"simple"}],"responses":{"200":{"content":{"application/vnd.mesh.v2+json":{"schema":{"$ref":"#/components/schemas/Tracking"}},"application/json":{"schema":{"$ref":"#/components/schemas/Tracking_1"}}},"description":"Successful Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"},"403":{"description":"Forbidden"}},"summary":"Track outbox","tags":["Tracking"]}},"/messageexchange/{mailbox_id}/outbox/tracking/{local_id}":{"get":{"deprecated":true,"description":"## Overview\nThis endpoint is now `deprecated` `tracking?messageID` should be used instead.","operationId":"tracking_by_local_id_messageexchange__mailbox_id__outbox_tracking__local_id__get","parameters":[{"description":"The user supplied (local ID) of the message","example":"api-docs-bob-sends-alice-a-chunked-file","explode":false,"in":"path","name":"local_id","required":true,"schema":{"description":"The user supplied (local ID) of the message","minLength":1,"title":"The local ID of the message","type":"string"},"style":"simple"},{"description":"mailbox identifier","example":"MAILBOX01","explode":false,"in":"path","name":"mailbox_id","required":true,"schema":{"description":"mailbox identifier","minLength":1,"title":"mailbox_id","type":"string"},"style":"simple"},{"description":"Authorisation header","example":"authorization: NHSMESH NONFUNC01:2c001608-5f09-4840-9611-bea43e666a30:1:201511201038:3cded68a9e0f9b83f2c5de1b79fc4dac45004523e6658d46145156fa6a03eced","explode":false,"in":"header","name":"authorization","required":true,"schema":{"default":"","description":"Authorisation header","title":"Authorization","type":"string"},"style":"simple"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tracking_1"}}},"description":"Successful Response"},"300":{"description":"Multiple Choices, the `local_id` is not unique"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"},"403":{"description":"Forbidden"}},"summary":"Track outbox (deprecated)","tags":["Tracking"]}},"/messageexchange/endpointlookup/{ods_code}/{workflow_id}":{"get":{"description":"## Overview\nUse this endpoint to search for the mailbox of the organisation you want to send data to, using their unique [Organisation Data Service (ODS) code](https://odsportal.hscic.gov.uk/Organisation/Search), their MESH mailbox and the agreed workflow identifier for the data.\n\nAn example call:\n\n### Request\n\n```shell\ncurl -k \\\n--cacert 'mesh-ca.pem' \\\n--key 'mesh-client-key.pem' \\\n--cert 'mesh-client-cert.pem' \\\n--header 'accept: application/vnd.mesh.v2+json' \\\nhttps://mesh-sync.spineservices.nhs.uk/messageexchange/endpointlookup/SCREEN2/SPINE_GPCAPITATION_EXTRACT\n```\n\n### Response\n\nfor `accept: application/vnd.mesh.v2+json`\n\n```json\n{\n  \"results\": [\n    {\"mailbox_id\": \"X2612345\", \"mailbox_name\": \"this is a test mailbox\"},\n    {\"mailbox_id\": \"X2612346\", \"mailbox_name\": \"this is a test mailbox too\"}\n  ]\n}\n```\n\nfor `accept: application/vnd.mesh.v1+json` or `accept: application/json`\n```json\n{\n  \"query_id\": \"20200601131040203367_A441C2_1573484974\",\n  \"results\": [\n    {\n      \"endpoint_type\": \"MESH\",\n      \"description\": \"Breast Cancer Screening Services\",\n      \"address\": \"X26HC022\"\n    },\n    {\n      \"endpoint_type\": \"MESH\",\n      \"description\": \"AAA Screening Services\",\n      \"address\": \"X26HC021\"\n    },\n    {\n      \"endpoint_type\": \"MESH\",\n      \"description\": \"Bowel Cancer Screening Services (England, DMS)\",\n      \"address\": \"X26HC020\"\n    }\n  ]\n}\n```\n\n**Note:** neither the ODS code or workflow identifier in this example are real.","operationId":"get_receiving_mailbox_ids_messageexchange_endpointlookup__ods_code___workflow_id__get","parameters":[{"description":"The ODS code of the organisation","explode":false,"in":"path","name":"ods_code","required":true,"schema":{"description":"The ODS code of the organisation","title":"ods_code","type":"string"},"style":"simple"},{"description":"The Workflow ID of the message","explode":false,"in":"path","name":"workflow_id","required":true,"schema":{"description":"The Workflow ID of the message","title":"workflow_id","type":"string"},"style":"simple"},{"description":"the accepts header can be used to vary the response type","example":"application/vnd.mesh.v2+json","explode":false,"in":"header","name":"accept","required":false,"schema":{"default":"application/json","description":"the accepts header can be used to vary the response type","title":"Accept","type":"string"},"style":"simple"}],"responses":{"200":{"content":{"application/vnd.mesh.v2+json":{"schema":{"$ref":"#/components/schemas/lookup_v2"}},"application/json":{"schema":{"$ref":"#/components/schemas/EndpointLookup"}}},"description":"Successful Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Look up MESH address","tags":["Lookup"]}},"/messageexchange/workflowsearch/{workflow_id}":{"get":{"operationId":"get_receiving_mailbox_ids_messageexchange_workflowsearch__workflow_id__get","parameters":[{"description":"The Workflow ID of the message","explode":false,"in":"path","name":"workflow_id","required":true,"schema":{"description":"The Workflow ID of the message","title":"workflow_id","type":"string"},"style":"simple"},{"description":"the accepts header can be used to vary the response type","example":"application/vnd.mesh.v2+json","explode":false,"in":"header","name":"accept","required":false,"schema":{"default":"application/json","description":"the accepts header can be used to vary the response type","title":"Accept","type":"string"},"style":"simple"}],"responses":{"200":{"content":{"application/vnd.mesh.v2+json":{"schema":{"$ref":"#/components/schemas/lookup_v2"}},"application/json":{"schema":{"$ref":"#/components/schemas/lookup_v2"}}},"description":"Successful Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Lookup by workflow","tags":["Lookup"]}}},"components":{"schemas":{"InboxCount":{"example":{"count":1234},"properties":{"count":{"description":"number of messages in the inbox","title":"Count","type":"integer"}},"required":["count"],"title":"InboxCount","type":"object"},"MeshError_1":{"example":{"messageID":"20220228174323222_ABCDEF","errorEvent":"SEND","errorCode":"01","errorDescription":"send failed for some reason"},"properties":{"messageID":{"description":"message_id associated with the error","title":"Messageid","type":"string"},"errorEvent":{"default":"","description":"message error phase","title":"Errorevent","type":"string"},"errorCode":{"default":"","description":"message error code","title":"Errorcode","type":"string"},"errorDescription":{"default":"","description":"message error description","title":"Errordescription","type":"string"}},"title":"MeshError","type":"object"},"Tracking":{"properties":{"message_id":{"description":"message identifier","title":"Message Id","type":"string"},"local_id":{"description":"local identifier supplied by sender","title":"Local Id","type":"string"},"workflow_id":{"description":"message workflow identifier","title":"Workflow Id","type":"string"},"filename":{"description":"local filename as supplied by the sender","title":"Filename","type":"string"},"expiry_time":{"description":"iso timestamp that the message will expire from the inbox","format":"date-time","title":"Expiry Time","type":"string"},"upload_timestamp":{"description":"iso timestamp that the message was accepted","format":"date-time","title":"Upload Timestamp","type":"string"},"recipient":{"description":"recipient mailbox identifier","title":"Recipient","type":"string"},"recipient_name":{"description":"recipient mailbox name","title":"Recipient Name","type":"string"},"recipient_ods_code":{"description":"recipient organisation ODS code","title":"Recipient Ods Code","type":"string"},"recipient_org_code":{"description":"recipient organisation organisation code","title":"Recipient Org Code","type":"string"},"recipient_org_name":{"description":"recipient organisation name","title":"Recipient Org Name","type":"string"},"status_success":{"description":"SUCCESS or ERROR if the message accepted","title":"Status Success","type":"boolean"},"status":{"description":"message status e.g. 'accepted' 'acknowledged'","title":"Status","type":"string"},"status_event":{"description":"status event","title":"Status Event","type":"string"},"status_timestamp":{"description":"iso timestamp last status change","format":"date-time","title":"Status Timestamp","type":"string"},"status_description":{"description":"status description","title":"Status Description","type":"string"},"status_code":{"description":"status code","title":"Status Code","type":"string"}},"required":["message_id"],"title":"Tracking","type":"object"},"LookupItem":{"properties":{"mailbox_id":{"description":"mailbox identifier","title":"Mailbox Id","type":"string"},"mailbox_name":{"description":"mailbox name","title":"Mailbox Name","type":"string"}},"required":["mailbox_id","mailbox_name"],"title":"LookupItem","type":"object"},"InboxCount_1":{"example":{"count":1234,"internalID":"20200601122152994285_af20cED","allResultsIncluded":true},"properties":{"count":{"description":"number of messages in the inbox","title":"Count","type":"integer"},"internalID":{"description":"internal identifier to help error diagnosis, be aware the format of this may change in line withinternal system changes and the format should not be parsed or validated or otherwise depended on","title":"Internalid","type":"string"},"allResultsIncluded":{"description":"indicates if the count was based on a partial result","title":"Allresultsincluded","type":"boolean"}},"required":["allResultsIncluded","count","internalID"],"title":"InboxCount","type":"object"},"MeshError":{"example":{"message_id":"20220228174323222_ABCDEF","internal_id":"20220228174323222_ABCDEF","detail":[{"event":"SEND","code":"01","msg":"send failed for some reason"}]},"properties":{"message_id":{"description":"message id associated with the error","title":"Message Id","type":"string"},"internal_id":{"description":"internal id associated with the error","title":"Internal Id","type":"string"},"detail":{"description":"error detail","items":{"type":"object"},"title":"Detail","type":"array"}},"title":"MeshError","type":"object"},"EndpointLookup":{"example":{"query_id":"20220228174323222_ABCDEF","results":[{"address":"X2612345","description":"this is a test mailbox","endpoint_type":"MESH"}]},"properties":{"query_id":{"description":"unique query identifier","title":"Query Id","type":"string"},"results":{"description":"list of matched mailboxes","items":{"$ref":"#/components/schemas/LookupItem_1"},"title":"Results","type":"array"}},"required":["query_id","results"],"title":"EndpointLookup","type":"object"},"Inbox_1":{"example":{"messages":["20220228174323222_ABCDEF","20220228174323333_ABCDEF"]},"properties":{"messages":{"description":"list of message ids in the inbox, up to `max_results`","items":{"type":"string"},"title":"Messages","type":"array"}},"required":["messages"],"title":"Inbox","type":"object"},"Location_inner":{"anyOf":[{"type":"string"},{"type":"integer"}]},"lookup_v2":{"example":{"results":[{"mailbox_id":"X2612345","mailbox_name":"this is a test mailbox"}]},"properties":{"results":{"description":"list of matched mailboxes","items":{"$ref":"#/components/schemas/LookupItem"},"title":"Results","type":"array"}},"required":["results"],"title":"lookup_v2","type":"object"},"SendMessage_1":{"example":{"messageID":"20220228174323222_ABCDEF"},"properties":{"messageID":{"description":"message identifier of the accepted message","title":"Messageid","type":"string"}},"required":["messageID"],"title":"SendMessage","type":"object"},"Tracking_1":{"properties":{"addressType":{"default":"ALL","title":"Addresstype","type":"string"},"checksum":{"description":"message status e.g. 'accepted' 'acknowledged'","title":"Checksum","type":"string"},"chunkCount":{"description":"number of message chunks","title":"Chunkcount","type":"integer"},"compressFlag":{"title":"Compressflag","type":"string"},"contentEncoding":{"default":"","title":"Contentencoding","type":"string"},"downloadTimestamp":{"description":"timestamp the message was acknowledged","title":"Downloadtimestamp","type":"string"},"dtsId":{"description":"message identifier of the sent message","title":"Dtsid","type":"string"},"encryptedFlag":{"title":"Encryptedflag","type":"string"},"expiryTime":{"description":"timestamp that the message will expire from the inbox","title":"Expirytime","type":"string"},"failureDate":{"title":"Failuredate","type":"string"},"failureDiagnostic":{"title":"Failurediagnostic","type":"string"},"fileName":{"description":"local filename as supplied by the sender","title":"Filename","type":"string"},"fileSize":{"description":"the uploaded file size","title":"Filesize","type":"integer"},"isCompressed":{"default":"","title":"Iscompressed","type":"string"},"linkedMsgId":{"description":"related message id","title":"Linkedmsgid","type":"string"},"localId":{"description":"local identifier supplied by sender","title":"Localid","type":"string"},"meshRecipientOdsCode":{"description":"recipient organisation ODS code","title":"Meshrecipientodscode","type":"string"},"messageId":{"description":"message identifier of the sent message","title":"Messageid","type":"string"},"messageType":{"description":"DATA or REPORT","title":"Messagetype","type":"string"},"partnerId":{"default":"","title":"Partnerid","type":"string"},"recipient":{"description":"recipient mailbox identifier","title":"Recipient","type":"string"},"recipientName":{"description":"recipient mailbox name","title":"Recipientname","type":"string"},"recipientOrgCode":{"description":"recipient organisation code","title":"Recipientorgcode","type":"string"},"recipientOrgName":{"description":"recipient organisation name","title":"Recipientorgname","type":"string"},"recipientSmtp":{"default":"","title":"Recipientsmtp","type":"string"},"sender":{"description":"sender mailbox identifier","title":"Sender","type":"string"},"senderName":{"description":"sender mailbox name","title":"Sendername","type":"string"},"senderOdsCode":{"description":"sender ods code","title":"Senderodscode","type":"string"},"senderOrgCode":{"description":"sender organisation code","title":"Senderorgcode","type":"string"},"senderOrgName":{"description":"sender organisation name","title":"Senderorgname","type":"string"},"senderSmtp":{"default":"","title":"Sendersmtp","type":"string"},"status":{"description":"message status e.g. 'accepted' 'acknowledged'","title":"Status","type":"string"},"statusCode":{"description":"status code","title":"Statuscode","type":"string"},"statusDescription":{"description":"status description","title":"Statusdescription","type":"string"},"statusEvent":{"description":"status event","title":"Statusevent","type":"string"},"statusSuccess":{"description":"SUCCESS or ERROR if the message accepted","title":"Statussuccess","type":"string"},"statusTimestamp":{"description":"timestamp of the status change","title":"Statustimestamp","type":"string"},"subject":{"description":"message subject","title":"Subject","type":"string"},"uploadTimestamp":{"description":"timestamp that the message was accepted","title":"Uploadtimestamp","type":"string"},"version":{"default":"1.0","title":"Version","type":"string"},"workflowId":{"description":"message workflow identifier","title":"Workflowid","type":"string"}},"required":["dtsId","fileSize","messageId"],"title":"Tracking","type":"object"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"loc":{"items":{"$ref":"#/components/schemas/Location_inner"},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"},"Inbox":{"example":{"messages":["20220228174323222_ABCDEF","20220228174323333_ABCDEF"],"links":{"self":"/messageexchange/mb12345/inbox?max_results=10","next":"/messageexchange/mb12345/inbox?max_results=10&continue_from=eyJwayI6ICJNQiNNU0cjTUIjMTIzNEhDMTIzNCMiLCAic2siOiAiTUIjTVNHIzIwMjIwMjI4MTc0MzIzMTIzX0FDREVEMSMifQ%3D%3D"},"approx_inbox_count":100},"properties":{"messages":{"description":"list of message ids in the inbox, up to `max_results`","items":{"type":"string"},"title":"Messages","type":"array"},"links":{"additionalProperties":{"type":"string"},"description":"map of links, e.g. `links.next` if more results exist","title":"Links","type":"object"},"approx_inbox_count":{"description":"approximate inbox count, this is eventually consistent and should be used as an indication of inbox size only","title":"Approx Inbox Count","type":"integer"}},"required":["messages"],"title":"Inbox","type":"object"},"SendMessage":{"example":{"message_id":"20220228174323222_ABCDEF"},"properties":{"message_id":{"description":"message identifier of the accepted message","title":"Message Id","type":"string"}},"required":["message_id"],"title":"SendMessage","type":"object"},"LookupItem_1":{"properties":{"address":{"description":"mailbox identifier","title":"Address","type":"string"},"description":{"description":"mailbox name","title":"Description","type":"string"},"endpoint_type":{"description":"mailbox endpoint type, this will always be MESH","title":"Endpoint Type","type":"string"}},"required":["address","description","endpoint_type"],"title":"LookupItem","type":"object"}}},"x-spec-publication":{"try-this-api":{"disabled":true}}}