Written by Technical Team | Last updated 27.09.2025 | 16 minute read
The Message Exchange for Social Care and Health (MESH) API is the national, production-grade service for moving data between health and care organisations across England. At its simplest, MESH is a reliable, secure post-restante for systems: a sender posts a file into a mailbox, the platform holds it durably, and the recipient collects it when their system is ready. Unlike ad-hoc SFTP silos or bespoke point-to-point integrations, the MESH API gives you a standardised, centrally governed pathway to move everything from structured HL7® FHIR® bundles and CSV extracts to binary artefacts and PDFs. It underpins key pathways such as pathology results into GP systems, discharge summaries, and large analytical extracts headed for NHS England.
For engineering teams, the API brings the qualities you expect from an enterprise transport layer: durable store-and-forward semantics, message tracking, and explicit acknowledgement of receipt. The service has been live since 2015 and is engineered for scale and availability—handling tens of millions of messages each month and supporting thousands of active mailboxes across the ecosystem. In practice, that translates into predictable performance characteristics, operational support 24×7×365, and a mature roadmap that continues to modernise the platform without breaking established workflows.
Critically, MESH is not a clinical messaging protocol; it’s the carriage. You still decide the payload format (for example FHIR, PDF, CSV, or encrypted binary) and agree the business semantics with your counterparties, but you avoid re-solving transport problems like retries, offline recipients, and message durability. That separation of concerns is why many national services mandate or recommend MESH for asynchronous exchange as part of conformance. It’s also why solution architects increasingly standardise on the API even when alternative transports exist internally—it reduces your vendor surface area and simplifies information governance discussions.
From a product perspective, MESH gives you options for how to plug in. There’s a fully documented REST API for direct integration, an installable client for file-drop–style automation, and a web user interface for one-off or low-volume transfers. The API and client support files up to 50 GB, making them suitable for sizeable datasets, while the UI suits small payloads and manual workflows. That flexibility matters in mixed estates where not every supplier stack is ready for a native API build.
Where MESH shines for delivery teams:
Every integration starts with a MESH mailbox—an addressable endpoint tied to an organisation’s ODS code. Your application authenticates as that mailbox, posts messages into recipients’ mailboxes, and polls your own inbox to download inbound items. You can maintain an address book of mailbox IDs for known trading partners, or you can look them up at runtime using the endpoint lookup service. That lookup takes an ODS code and a Workflow ID (more on workflows in a moment) and returns the matching mailbox(es) to address your message to. For GP-directed flows, you can even have MESH resolve the patient’s registered practice dynamically.
Workflows are the API’s way of classifying what’s inside the envelope. A Workflow ID is mandatory in each message and signals the type of content—for example, a particular discharge summary variant or a GP Connect operation. Mailboxes are granted membership of “workflow groups” which determine what they can send and receive. This mechanism does two things for you: it helps recipients route and process messages correctly, and it provides governance that prevents a mailbox from being spammed with content it shouldn’t receive. If you’re designing a new regional or national integration, agreeing and registering the appropriate Workflow IDs up front is an essential step.
When you don’t know a mailbox ID, you have a few supported options. First, MOLES (the MESH Online Enquiry Service) lets authorised users search via a web UI. Second, the REST endpoint-lookup interface allows programmatic search from your application. Third, for specific GP-routing use cases, you can instruct MESH to look up the patient’s GP mailbox on your behalf by encoding patient details in the Mex-To header or control file field using a prescribed GPPROVIDER_<NHS Number>_<YYYYMMDD DOB>_<Surname> pattern. This triggers a Spine demographic check and resolves the practice into a mailbox transparently during delivery.
Headers carry the routing and tracking metadata that glue the lifecycle together. In practice, you’ll set fields such as mex-from (your sending mailbox), mex-to (the destination mailbox or the special GP-routing directive), mex-workflowid (the content classification), and a local correlation reference in mex-localid. Some consuming services, such as NHS Notify’s MESH integration, also expect a mex-subject aligned to their routing plan; the platform will echo back your local ID and confirm the workflow in its acknowledgement, helping you build idempotent, end-to-end reconciliation.
Finally, keep in mind that mailbox ownership and workflow entitlements are controlled centrally. If you’re onboarding a new organisation, plan time to obtain or update mailboxes, associate the correct workflows, and—if you rely on the endpoint lookup—ensure the target ODS codes are discoverable for your workflows. These are predictable tasks, but they do involve coordination between your programme, the recipient, and NHS England platform teams.
MESH connections are protected end-to-end with mutual TLS, meaning both sides present and validate X.509 certificates at session establishment. This is not optional: whether you connect over HSCN or via the Internet Gateway, your client must hold a valid certificate issued under the NHS trust chain. Historically, Internet-facing access used third-party CAs; that process has been simplified so Internet consumers now follow the same NHS certificate enrolment route. Certificates last three years, and if one expires your client will immediately lose access, so your operational runbooks should include expiry monitoring and timely renewals.
From an addressing perspective, the base URLs vary by network path. If you’re consuming the endpoint-lookup service using a Spine certificate over HSCN, you call the simple-sync path; if you’re using a MESH certificate, you use the mesh-sync path. For Internet access to the core service, clients should be configured to use the mesh-sync.spineservices.nhs.uk primary URL. These details matter when you build multi-environment automation—don’t hardcode a single domain across test and live, and document which certificate each environment is using.
It’s also useful to distinguish identity for people versus systems. The web UI authenticates human users through NHS Care Identity Service 2 (CIS2) and is intended for manual, low-volume transfers. The API and client authenticate machine-to-machine and are the default for production automation. That separation reinforces least-privilege principles: developers and operations engineers can interactively track messages via MOLES when needed, whilst your services move data autonomously through the API.
A typical lifecycle looks like this: your application prepares a payload, sets routing headers, posts the message to MESH, and records a local correlation ID. The platform persists the message and exposes it to the recipient’s inbox. Your counterpart polls their inbox on a schedule, downloads the payload when available, and sends a positive acknowledgement to remove it from the queue. If nobody acknowledges within the five-day retention window, MESH generates a non-delivery report back to the sender’s mailbox so you can reconcile and retry or escalate. This store-and-forward model removes time coupling between parties and is resilient to transient outages on either side.
Headers carry the metadata that make the lifecycle observable. mex-localid is your friend for idempotency and correlation; use a stable value per logical message so that if you retry a submission you can de-dupe downstream. mex-workflowid allows receivers to route the file to the right business pipeline, and mex-subject can be repurposed by some workflows for plan or template identifiers. When the recipient downloads the file successfully, they send the API’s acknowledgement, which both removes the item from the inbox and serves as a durable receipt for your audit trail. Many programmes then add a higher-level, business-semantic acknowledgement in their payload protocol (for example, a FHIR OperationOutcome or an ACK file) to signal processing success beyond transport.
MESH is engineered for big files. With the API or the installable client, you can push payloads up to 50 GB. Under the covers, the platform supports “large message” chunking: you break a payload into sequential chunks that MESH reassembles for the receiver. Correct chunk sizing is essential—do not send tiny fragments. As a rule, ensure each decompressed chunk (apart from the final one) exceeds 5 MiB, and keep chunk sizes below the platform’s maximum per-chunk threshold. Teams have found that overly aggressive compression can produce chunks that are too small after decompression, leading to validation errors; sizing against the uncompressed dimension avoids that pitfall.
The inbox/outbox model drives your API choreography. On the sending side, you post to your outbox, then track delivery status against the message identifier returned by the platform. On the receiving side, you poll your inbox for new items, download each message (reassembling if it was chunked), and explicitly acknowledge the successful download to clear it. Implement retry with exponential back-off for both download and acknowledgement operations; the service is designed to be robust to duplicates and transient failures, but your client should still be polite and avoid hammering.
To embed this into your platform reliably, adopt a small set of operational conventions from day one:
Teams that succeed with MESH design for decoupling. On the send side, collect payloads into a durable queue (for example, your application database or a message broker), have a stateless worker transform them into MESH messages, and treat the API call as an external dependency with its own retry and circuit-breaker policy. On the receive side, treat the MESH inbox as a transient buffer only; the first thing you do after download is write the file and its metadata to your own durable store with the mex- headers and message identifier. With that pattern, your business processing pipeline has exactly-once semantics even if the transport gives you at-least-once delivery. It’s a pragmatic split that contains failure domains neatly.
Chunking deserves deliberate design. If you’re sending multi-gigabyte files, calculate chunk boundaries in advance and favour a fixed uncompressed size for all but the last fragment. Compress for transit if you wish, but size against the uncompressed dimension so you don’t trip minimum thresholds after compression. Track a running checksum per chunk and a whole-file checksum; include both in your metadata so the receiver can verify integrity before acknowledging. Teams who do this report shorter incident investigations because they can prove whether corruption occurred pre- or post-transit.
Throughput is rarely limited by the platform so much as client design. Long-polling with short intervals is tempting, but noisy; instead, pick a sensible cadence that balances latency and resource use—many adopters start with a 30–60 second poll for business-critical workflows and slacken off for batch windows. The API guidance also recommends periodic mailbox validation (for example, once every 24 hours) as a health check. This is particularly helpful in containerised deployments where clients can lose certificates or DNS configuration across restarts; a daily validation call surfaces those issues before they cause missed messages.
Give yourself strong correlation from day one. mex-localid should be unique per logical message or batch, stable across retries, and linked to your internal identifiers (for example, episode ID or extract run ID). When you receive an acknowledgement or a non-delivery report, echo it through your observability layer with that same correlation key so product teams and clinical safety officers can trace an item end-to-end quickly. For high-volume senders, consider namespacing: prefix the local ID with a system or workflow code so you can route logs and dashboards by function without deep packet inspection. When you integrate with third-party services that sit behind MESH (like NHS Notify), read their header expectations carefully—fields such as mex-subject may have specific semantics in their workflows.
Idempotent receivers are just as important. If your inbox worker downloads the same message twice because a previous acknowledgement didn’t stick, you must recognise and discard the duplicate safely. A simple pattern is to record the MESH message identifier alongside a hash of the payload; if both match a record marked complete, skip processing and send the ack. This is also where chunking checksums pay off: if a reassembled payload differs, you have hard evidence for a targeted re-pull or incident ticket rather than a “works for me” back-and-forth.
MESH gives you transport-level observability and a centralised tracking console via MOLES. Use both. Your application should emit its own metrics—send attempts, successful posts, inbox poll latency, download errors, acknowledgement latency—and correlate those with platform-level states exposed through the API. MOLES remains invaluable when two organisations disagree about what happened to a message; an authorised user can step through the message lifecycle and match timestamps on either side. If you run 24×7 services, give your on-call engineers MOLES access and a runbook that explains how to pull evidence for partner support teams.
Alert on the negative space, not just the errors. For example, if you expect at least one inbound extract overnight and nothing arrives by a certain hour, page the team; likewise, alert on a rising backlog in your outbox or on a spike in NDRs. These are the signals that indicate a broken upstream job, an expired certificate, or a network change at a partner site—even when your logs look healthy.
Plan your onboarding as a miniature project. You will need to: obtain the right certificate (or confirm your Spine endpoint certificate covers your use), request or confirm a mailbox per organisation, ensure appropriate workflow group entitlements, and configure your network path (HSCN or Internet Gateway). Certificates are valid for three years; add expiry dates to your configuration registry and build a renewal reminder into your operational calendars. If you’re renewing an older Internet certificate, remember to update the primary URL to the current Internet Gateway domain to avoid connection failures after the switch.
Treat environments deliberately. There are distinct integration and production mailboxes for many national services. For example, NHS Notify publishes separate mailbox IDs for integration testing and for live traffic; use the right one for the right phase and automate that choice via configuration rather than code. When you move a workflow from test to live, run a formal readiness review: check workflow entitlements, confirm both sides’ certificate validity windows extend beyond the go-live period, and walk through failure drills (bad mailbox ID, chunk size too small, recipient offline) so your on-call team knows what to do on night one.
Change is steady, not sudden. The platform publishes a roadmap and periodically deprecates older client versions while improving operational capabilities such as backup and self-service. Subscribe to update channels and plan minor upgrades into your quarterly maintenance windows rather than waiting for a forced march—your clinical safety case will thank you. If you supply software into the NHS, communicate your tested MESH versions in release notes so trusts can plan their own upgrades with confidence.
Most incidents come down to four broad categories: certificate problems, chunking errors, mailbox mis-routing, and misunderstanding of acknowledgements. Certificates first: verify the trust chain on both sides and check expiry. Many “sudden” outages are simply expired certs or clients misconfigured after a server patch. Chunking next: if you see validation errors for large messages, revisit your chunk size logic—ensure each decompressed chunk, except the last, exceeds the minimum size, and avoid excessively small compressed fragments.
Routing problems typically appear when a new organisation is onboarded or when an ODS code changes. If endpoint lookup returns multiple results, you may need to disambiguate with a more specific workflow or work with the recipient to consolidate mailboxes. For GP-directed flows using the GPPROVIDER_… pattern, errors like “invalid NHS number” or “no demographics match” will be reported, but remember that these are delivered as error reports into your mailbox rather than inline API failures—monitor for them explicitly and add alerting so they don’t silently pile up.
Finally, be clear about what an acknowledgement means. The MESH transport-level ack confirms the recipient’s system has downloaded the file, not that it has processed it successfully. If your assurance story needs full chain-of-custody, design a business-level acknowledgement pattern at the payload layer—many programmes send a separate message or status update confirming processing completion. Getting this distinction right avoids false positives in assurance dashboards and reduces friction between suppliers and trusts during incident reviews.
The MESH API gives healthcare IT teams a dependable foundation for cross-organisational data exchange: mutual-TLS security, durable store-and-forward delivery, explicit receipt semantics, and a governance model built around Workflow IDs and mailbox entitlements. To make the most of it, architect for idempotency and decoupling, size large-message chunks by uncompressed limits, automate certificate lifecycle and environment selection, and wire robust monitoring around both your application behaviour and the platform’s transport signals. Do that, and you’ll have an integration that scales from a few discharge summaries a day to multi-gigabyte national extracts—without rewriting your transport every time a new partner comes on board.
If you’re standing up your first MESH integration, a sensible path is: secure your certificate and mailbox, validate connectivity to the appropriate base URL, send a trivial text payload to a known test mailbox to prove your headers and acknowledgements are correct, then graduate to your real payload and chunking scheme. Keep MOLES in your back pocket for joint investigations, and document who to call for mailbox or workflow entitlements. Once live, your team should find that MESH gets out of the way and lets you focus on the business semantics of the data you’re moving—exactly as a transport layer should.
Is your team looking for help with MESH integration? Click the button below.
Get in touch