--- title: XDR-Based Messaging Best Practices slug: xdr/guide/xdr-based-messaging-best-practices docTags: createdAt: 2026-07-30T21:09:39.087Z --- This section describes best practices that improve message reliability, interoperability, and workflow continuity. They complement the [Application Certification Requirements](docId\:WsFITp7Dv6u1yRn7zBxD8) by reducing operational risk and improving end-user outcomes. Customers are encouraged, but not required, to follow them. ## Message Submission and Retry XDR-based messaging operates across multiple systems and networks, so temporary outages can occur. Design for retry and resiliency to prevent message loss and reduce manual rework. Retry submissions when temporary connection failures occur, using a controlled schedule with exponential backoff (for example, after 5, 15, 30, and 60 minutes) over a bounded window of roughly two hours. Distinguish retryable errors (network timeouts, 503 Service Unavailable) from non-retryable errors (authentication failures, invalid message format). Do not retry non-retryable errors; surface them for correction. Queue outbound messages that cannot be sent immediately so users can continue working without resending manually. Treat retry as an operational safeguard, not an error state; users should only be involved when retries are ultimately exhausted. ## Delivery Status Notifications Synchronous responses confirm processing, not final delivery. Use DSNs ([Delivery Status Notification (DSN)](docId\:daGa7Uw8ataRiYlZ3RtU9)) as the signal of delivery outcome, and reflect that status in the user's workflow. Ensure your account is configured (opt-in) to receive delivery notifications; DSN behavior is governed by that configuration, not by the message alone ([Delivery Status Notification (DSN)](docId\:daGa7Uw8ataRiYlZ3RtU9)). Surface delivery status clearly to users, using a state model such as the one below, and display the reasonForFailure text on failures. Distinguish a timeout-driven DSN Failure from a genuine delivery failure. A timeout means no delivery confirmation was returned - often because the recipient is served by a HISP that does not support delivery tracking - so the message may still have been delivered. Treat it as unconfirmed rather than definitively failed ([Delivery Status Notification (DSN)](docId\:daGa7Uw8ataRiYlZ3RtU9)). Process a DSN for each recipient when a message was addressed to multiple recipients. The following state model reconciles the synchronous response and the DSN into a single delivery status you can present to users: | **State** | **Meaning** | **Source** | | ------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------- | | Submitted | The message has been sent to Surescripts; no synchronous response yet. | Local (sending workflow) | | Accepted | Surescripts accepted the message for delivery; not yet delivered. | Synchronous Success response | | Rejected | Surescripts could not accept the message. | Synchronous Failure response | | Delivered | The message reached the recipient. | DSN Success | | Failed | The message was not delivered; a reason is provided. | DSN Failure with a delivery error | | Unconfirmed | No delivery confirmation was returned within the timeout; the message may still have been delivered. | DSN Failure due to timeout | | Partially Delivered | For a multi-recipient message, outcomes differ across recipients (some delivered, some failed or unconfirmed). | Per-recipient DSNs | :::hint{type="info"} **Note:** "Retrying" is a useful transient state while a submission is being retried after a temporary connection failure ([Message Submission and Retry](docId\:zA3pMlbsxejAs5vduvf55)), before it reaches Accepted or Rejected. ::: ## Message Context and Threading Many clinical workflows rely on back-and-forth communication. Proper message identification keeps replies associated with the right conversation. Populate MessageID on every message and RelatesTo on every reply or notification ([Message Identification](docId\:xZ0MTs_W6FVT5WxkvD-Q0)). Associate replies with the originating request so follow-up actions - referral responses, care-coordination questions, public-health clarifications - can be tracked accurately. ## Patient Matching Accurate patient identification is essential when exchanging documents across organizations. Even when identifiers are present, downstream systems must verify and reconcile them. Include patient identifiers and demographics whenever available to support accurate association. Do not rely on XDR metadata alone for matching; when metadata is insufficient, inspect the attachment types you expect to receive (C-CDA XML or HTML, HL7 v2, PDFs, and other supported documents) for additional demographics or identifiers. Use Object Identifiers (OIDs) as the assigning authority for patient identifiers where possible. For example, a CX-formatted identifier is PATID1234^^^&1.3.6.1.4.1.99999.1\&ISO, where 1.3.6.1.4.1.99999.1 is the assigning authority's OID. Organizations can obtain an OID from the HL7 OID registry (see [Document References](docId\:zT9Op0w2lVchwQV38E85W)). Design workflows that let users review and confirm patient matches when identifiers originate from external systems, and correct mismatches without re-sending. Route messages with missing or ambiguous patient data to a triage or review queue rather than silently failing or misrouting. ## Clinical Attachments Participants vary in the document types they can send and receive. Supporting multiple formats improves interoperability. Accept common clinical document types, in roughly this priority: C-CDA, PDF, plain text, CCR, and images (PNG, JPG). At minimum, support C-CDA and PDF. For the best user experience, provide direct viewing support for common clinical attachment types where practical. Regardless of viewing capability, applications must still satisfy the attachment download requirements in ACR C.205. When an attachment is filtered or removed, notify the recipient that it was removed, in accordance with ACR C.205. A sender-facing notification may also be implemented as a workflow enhancement, but it does not substitute for recipient-facing notification. Do not rely on attachment file names for document identification, routing, classification, or patient matching; file names are not preserved end-to-end. Use metadata, document identifiers, MIME/content type, and document content instead. Treat the clinical document(s) and their metadata as the authoritative content of a message; do not rely on plaintext message body text as a clinical payload, since it is optional and is not guaranteed to be retained end to end. ## Metadata Metadata supports routing, matching, and downstream processing. Richer metadata improves interoperability even when document content varies. Follow the applicable DirectTrust/IHE metadata requirements for the profile you implement; Surescripts does not enforce metadata beyond the standards. Include the common document classifications ([Message Metadata](docId\:xZ0MTs_W6FVT5WxkvD-Q0)) when your system can produce them, as they improve downstream routing and filing. Use Full XDS Metadata when integrating with an XDS registry or repository, or when a use case or regulation requires it. Preserve metadata consistently as messages pass through systems to avoid data loss or misinterpretation. ## Error Management Handling errors you receive: - Handle SOAP Faults and XDR application-level errors as distinct failure types ([XDR-Based Messaging Errors](docId:6daoSZCLi671QoVLxx3uD)). - Do not assume a SOAP success implies message acceptance or delivery. - Do not branch programmatically on RegistryError/@errorCode or codeContext in a Surescripts-generated failure. errorCode carries descriptive text that can change between releases, and codeContext carries a fixed general value; neither is a stable identifier. Use the RegistryResponse Failure status as the machine-readable signal and treat the rest as diagnostic detail. - Log complete RegistryError details for troubleshooting, and display user-friendly messages rather than raw SOAP faults or raw errorCode text. Producing errors your system returns (see [Sending the Message Response](docId\:XyQrOSGPZ8458uzH0p8sU)): - When you cannot accept a message, return a valid RegistryResponse with a Failure status and a RegistryErrorList; do not fail silently or return a Success you cannot honor. - Populate a specific, standards-based errorCode and an actionable codeContext, so the sender can respond programmatically and a person can understand the cause. - For delivery failures reported by DSN, provide a specific reasonForFailure (for example, "Mailbox not found.") rather than a generic message. - Do not include PHI or other sensitive detail in error text, consistent with ACR C.203, which keeps PHI out of message subjects. - Keep your error semantics consistent so trading partners can rely on them. ## Directory Management To support consistent, searchable, high-quality Direct address directory data: Publish and maintain your Direct addresses in the Surescripts Directory; directory publication is the expected routing model ([Receiving Flow Overview](docId\:XyQrOSGPZ8458uzH0p8sU)). See the Surescripts Directory Implementation Guide for details, and [Relationship to Your Surescripts Agreement](docId\:pmVq7Uy_7YMaKt3XdRoA1) for the corresponding Directory obligations. Keep the addresses you publish synchronized with your source systems and accurate and up to date; stale or incorrect entries cause misrouting and delivery failures. Support manual entry of Direct addresses. Not every valid Direct address is published in the Directory, so let users enter and save an address they have obtained directly and send to recipients who are not listed. Display key provider information alongside each Direct address so users can confidently identify the intended recipient. Clearly distinguish individual-provider addresses from organizational (non-provider) addresses to reduce misrouting. Support intuitive search (provider name, Direct address, specialty, organization, NPI) and filtering, and provide data-quality or verification indicators. ## Prefer Single-Recipient Messages Although Surescripts accepts multiple direct\:to recipients on one message, it splits multiple-recipient messages for routing. Sending a separate message per recipient produces more predictable delivery and tracking, and simplifies per-recipient DSN handling. Reserve multiple-recipient messages for cases where the sending workflow genuinely requires them.