{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Message Delivery Model","description":"Developer documentation for integrating systems that send messages, plus reporting and operational APIs for platform holders."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"message-delivery-model","__idx":0},"children":["Message Delivery Model"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Digital Post Platform uses an envelope-based submission model, where each envelope contains sender, recipient, and message content. The envelope also contains additional message features such as, for example, Interim Repository, Multiple Recipients, Scheduled Delivery, Opening Receipts. For in depth descriptions on message features refer to the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/documentation/delivery#message-features"},"children":["Message Features"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A delivery groups one or more envelopes into a single request, enabling efficient submission of multiple messages."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"core-concepts","__idx":1},"children":["Core Concepts"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The delivery model is based on the following core components."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"envelope","__idx":2},"children":["Envelope"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An envelope is the unit used to send a message. It is a structured JSON object that defines:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Who is sending the message"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Who should receive it"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["What content should be included"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["References to the files associated with the message"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each envelope represents exactly one message."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Files are not embedded in the envelope. Instead, the envelope references the files that should be delivered."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An envelope may contain multiple recipients (up to 10)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["20 identical messages to 20 recipients → 2 envelopes (10 recipients in each)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["20 different messages to 20 recipients → 20 envelopes (1 recipient in each envelope)"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"message-content","__idx":3},"children":["Message Content"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Message content consists of:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["One primary body file"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Zero or more attachments"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Files are stored externally in object storage and referenced from envelopes."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["During processing, files are validated, scanned, and encrypted for delivery."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"delivery","__idx":4},"children":["Delivery"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A delivery represents a single submission request to the platform."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A delivery contains:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["One or more envelopes"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["References to message files"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Connection details for content storage"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Optional encryption information"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each delivery is processed independently."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"submission-options","__idx":5},"children":["Submission Options"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"file-based-submission-s3","__idx":6},"children":["File-Based Submission (S3)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In file-based submission, message data is uploaded to a storage bucket (such as Amazon S3) under a specific prefix (a sender-defined folder-like path), and referenced when initiating a delivery."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before calling the API, the sender prepares a storage location containing:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["One or more ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["envelope files"]}," (JSON), each defining a message"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Any ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["documents"]}," referenced by those envelopes (message body and attachments)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All files related to a delivery are placed under a common prefix, which represents a single delivery. Within this structure:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Envelope files are stored under a dedicated sub-prefix (e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<prefix>/<envelope prefix>/"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["All referenced documents are stored directly under the main prefix"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A delivery may contain multiple envelopes (e.g., different message types such as payslips or fines), but all are processed as part of the same delivery."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A typical setup:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"<prefix>/\n  document1.pdf\n  document2.pdf\n  <envelope prefix>/\n    envelope1.json\n    envelope2.json\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each envelope references its corresponding documents by file name within the same location."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the delivery is created, the platform retrieves the envelopes from the envelope sub-prefix and the associated documents from the main prefix, and processes them together as a single delivery."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"file-based-submission-flow-high-level-overview","__idx":7},"children":["File-Based Submission Flow (high level overview)"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Upload envelopes and documents to a bucket under a prefix (one prefix per delivery)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Call ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/delivery/delivery/other/createdelivery"},"children":["Create delivery via S3"]}," with the bucket and prefix."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The platform retrieves files from storage."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Envelopes are processed, and messages are delivered."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For request structure and required parameters, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/delivery/delivery/other/createdelivery"},"children":["Create delivery via S3"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"multipart-submission","__idx":8},"children":["Multipart Submission"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In multipart submission, message data is sent directly in the API request as a multipart payload."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Instead of uploading files to external storage, the sender includes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The envelope (JSON)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The message body and attachments (as file parts)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All components are submitted together in a single request, forming one delivery."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each envelope defines the message structure (sender, recipients, content), while the associated files are included inline and referenced within the same request."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Multipart submission is typically used when:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Messages are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["small to medium in size"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The sender does ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not use external storage"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Simpler integration is preferred over high-volume throughput"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the request is received, the platform processes the envelopes and associated files directly without retrieving content from external storage."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"multipart-submission-flow-high-level-overview","__idx":9},"children":["Multipart Submission Flow (high level overview)"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Build an envelope JSON."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Attach message body and files as multipart parts."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Call ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/delivery/delivery/other/createmessagebundle"},"children":["Create delivery (multipart)"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The platform processes the request directly."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Multipart submission is subject to request size limits and is not recommended for high-volume deliveries."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For request structure and required parameters, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/delivery/delivery/other/createmessagebundle"},"children":["Create delivery (multipart)"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"delivery-guarantees","__idx":10},"children":["Delivery Guarantees"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The platform enforces ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["atomic delivery at the envelope level"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This means that for each envelope:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Either all recipients receive the message, or no recipients receive the message"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An envelope is never partially delivered"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each envelope is processed independently within a delivery."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As a result, a delivery may succeed in some envelopes and fail for others."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"delivery-states","__idx":11},"children":["Delivery States"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After submission, deliveries progress through a series of processing states."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For checking delivery and envelope outcomes, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/documentation/status-reporting"},"children":["Status Reporting"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"errors-and-retries","__idx":12},"children":["Errors and Retries"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If a request fails or a delivery cannot be processed as expected, the platform returns error responses and provides mechanisms to monitor outcomes and retry operations."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["For details on error responses, formats, and error codes, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api/errors"},"children":["Error Handling"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["For guidance on retrying failed requests or deliveries, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/documentation/status-reporting"},"children":["Retry Strategy"]},"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"performance-considerations","__idx":13},"children":["Performance Considerations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Delivery performance may vary depending on delivery size, file size, and processing complexity."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"relationship-to-other-models","__idx":14},"children":["Relationship to Other Models"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The delivery model relies on other core platform concepts:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/documentation/organisational-model"},"children":["Organisational Model"]}]}," – defines the structure of organizations, sub-organizations, and senders"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api/authentication"},"children":["Authentication Model"]}]}," – defines how requests are authorized"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/documentation/message-lifecycle"},"children":["Message Lifecycle"]}]}," – describes how messages are processed after submission"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Refer to these sections for additional context when integrating with the platform."]}]},"headings":[{"value":"Message Delivery Model","id":"message-delivery-model","depth":1},{"value":"Core Concepts","id":"core-concepts","depth":2},{"value":"Envelope","id":"envelope","depth":3},{"value":"Message Content","id":"message-content","depth":3},{"value":"Delivery","id":"delivery","depth":3},{"value":"Submission Options","id":"submission-options","depth":2},{"value":"File-Based Submission (S3)","id":"file-based-submission-s3","depth":3},{"value":"File-Based Submission Flow (high level overview)","id":"file-based-submission-flow-high-level-overview","depth":4},{"value":"Multipart Submission","id":"multipart-submission","depth":3},{"value":"Multipart Submission Flow (high level overview)","id":"multipart-submission-flow-high-level-overview","depth":4},{"value":"Delivery Guarantees","id":"delivery-guarantees","depth":2},{"value":"Delivery States","id":"delivery-states","depth":2},{"value":"Errors and Retries","id":"errors-and-retries","depth":2},{"value":"Performance Considerations","id":"performance-considerations","depth":2},{"value":"Relationship to Other Models","id":"relationship-to-other-models","depth":2}],"frontmatter":{"title":"Message Delivery Model","description":"Understand how digital messages are submitted, validated, processed, and delivered through the Digital Post Platform.","seo":{"title":"Message Delivery Model"}},"lastModified":"2026-05-06T09:31:17.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/documentation/delivery-model","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}