sedex Envelope Format

The envelope is a critical component of the sedex messaging system. It serves as the cover letter for each message, providing essential metadata required for secure and efficient message delivery.

Structure of the Envelope🔗

Envelopes of File-based messaging are written in XML format. The schema is defined in eCH-0090 version 1
Envelopes of REST API-based messaging are represented in JSON format, defined in the OpenAPI specification.

It includes the following mandatory and optional elements:

messageId: (Mandatory) A unique identifier for the message, generated by the sending application.
messageType: (Mandatory) Specifies the type of the message (e.g., business case).
messageClass: (Mandatory) Defines the purpose of the message, based on the business case:
- 0: Initial message.
- 1: Response to a message.
- 2: Receipt or acknowledgment.
- 3: Error notification.
messageReferenceId: (Optional) A reference to the messageId of another message. This field is typically used when the current message is a response or relates to another message in a business context.
senderId: (Mandatory) Identifies the sedex participant sending the message.
recipientId: (Mandatory) Identifies one or more sedex participants intended to receive the message.
eventDate: (Mandatory) The date of the event referenced in the message payload.
messageDate: (Mandatory) The timestamp when the message was created.

Example:

File-based XMLREST API-based JSON

<?xml version="1.0" encoding="UTF-8"?>
<envelope xmlns="http://www.ech.ch/xmlns/eCH-0090/1"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.ech.ch/xmlns/eCH-0090/1 https://www.ech.ch/xmlns/eCH-0090/1/eCH-0090-1-0.xsd"
          version="1.0">
    <messageId>62fdee70d9ea77646f6e8686a3f9332e</messageId>
    <messageType>99</messageType>
    <messageClass>0</messageClass>
    <senderId>1-1234-1</senderId>
    <recipientId>3-CH-1</recipientId>
    <eventDate>2025-01-01T00:00:00</eventDate>
    <messageDate>2025-09-06T14:13:51</messageDate>
</envelope>

{
  "document-type": "envelope",
  "document-version": "1.0",
  "sender-id": "1-1234-1",
  "recipient-ids": [
    "3-CH-1"
  ],
  "message-type": 99,
  "message-class": 0,
  "message-id": "62fdee70d9ea77646f6e8686a3f9332e",
  "message-date": "2025-09-06T14:13:51",
  "event-date": "2025-01-01T00:00:00",
  "loopback": false
}

DateTime Format🔗

The dates must be specified in the following format: yyyy-MM-ddTHH:mm:ss:fffZ

yyyy: the current year
MM: the current month
dd: the current day
HH: the current hour in 24-hour format
mm: the current minute
ss: the current second
fff (optional): the current fraction of a second (only up to six digits are supported, see note about time precision)
Z (optional): Timezone of the time, e.g. +02:00 for UTC + 2 hours

Time Precision

Although the XML DateTime format would support more than six digits for the fraction of a second, sedex deliberately allows a maximum of six digits. This is to ensure compatibility with older systems.
If the sender of a sedex message specifies more than six digits in the envelope, the transmission is aborted with a receipt (Staus code: 200, invalid envelope syntax).

Sending a Message to Multiple Recipients🔗

sedex supports sending a single message to multiple recipients. This feature allows the sender to address multiple sedex participants in one operation by listing all their IDs in the recipientId field of the envelope.

How It Works:

The recipientId element can include one or more IDs of sedex participants.
For each recipient, the sedex-Client generates an individual delivery receipt, enabling the sender to track the status of the message for each recipient.

Example

File-based XMLREST API-based JSON

<?xml version="1.0" encoding="UTF-8"?>
<envelope xmlns="http://www.ech.ch/xmlns/eCH-0090/1"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.ech.ch/xmlns/eCH-0090/1 http://www.ech.ch/xmlns/eCH-0090/1/eCH-0090-1-0.xsd"
          version="1.0">
    <messageId>62fdee70d9ea77646f6e8686a3f9332e</messageId>
    <messageType>99</messageType>
    <messageClass>0</messageClass>
    <senderId>1-1234-1</senderId>
    <recipientId>3-CH-1</recipientId>
    <recipientId>4-CH-2</recipientId>
    <recipientId>5-CH-3</recipientId>
    <eventDate>2025-01-01T00:00:00</eventDate>
    <messageDate>2025-09-06T14:13:51</messageDate>
</envelope>

{
  "document-type": "envelope",
  "document-version": "1.0",
  "sender-id": "1-1234-1",
  "recipient-ids": [
    "3-CH-1",
    "4-CH-2",
    "5-CH-3"
  ],
  "message-type": 99,
  "message-class": 0,
  "message-id": "62fdee70d9ea77646f6e8686a3f9332e",
  "message-date": "2025-09-06T14:13:51",
  "event-date": "2025-01-01T00:00:00"
}

Error Handling with Multiple Recipients

If one or more recipients are unauthorized:

The sedex-Client will reject the entire message. This means that the message will not be delivered to any of the recipients.
An error receipt will be generated for each recipient. This receipt will clearly indicate the issue, specifying which recipient(s) were unauthorized and caused the rejection.

Message Types and Classes🔗

The envelope includes key routing metadata, such as:

messageType: Defines the use case or business scenario for the message.
messageClass:
- 0: Initial message.
- 1: Response to a message.
- 2: Acknowledgment or receipt.
- 3: Error notification.

Example Use Case

A business transaction may involve:

A sender transmitting an initial message (messageClass=0).
The recipient confirming receipt with a response (messageClass=1).
An error notification being issued if processing fails (messageClass=3).

Message Reference ID🔗

The messageReferenceId is an optional element in the sedex envelope. It allows the sender to reference the messageId of a previously sent message. This feature is particularly useful in workflows where messages are logically linked, such as responses or error notifications. By referencing the messageId of an earlier message, the sender can:

Indicate that the current message is a response to a previous one.
Link an error notification to the message that caused the error.
Support complex workflows where multiple messages are interdependent.

Example

This is an example of an envelope that includes the messageReferenceId:

File-based XMLREST API-based JSON

<?xml version="1.0" encoding="UTF-8"?>
<envelope xmlns="http://www.ech.ch/xmlns/eCH-0090/1"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.ech.ch/xmlns/eCH-0090/1 https://www.ech.ch/xmlns/eCH-0090/1/eCH-0090-1-0.xsd"
          version="1.0">
    <messageId>response-message-id-12345</messageId>
    <messageType>99</messageType>
    <messageClass>1</messageClass>
    <referenceMessageId>original-message-id-67890</referenceMessageId>
    <senderId>1-1234-1</senderId>
    <recipientId>3-CH-1</recipientId>
    <eventDate>2025-01-01T00:00:00</eventDate>
    <messageDate>2025-09-06T14:13:51</messageDate>
</envelope>

{
  "document-type": "envelope",
  "document-version": "1.0",
  "sender-id": "1-1234-1",
  "recipient-ids": [
    "3-CH-1"
  ],
  "message-type": 99,
  "message-class": 1,
  "message-id": "response-message-id-12345",
  "reference-message-id": "original-message-id-67890",
  "message-date": "2025-09-06T14:13:51",
  "event-date": "2025-01-01T00:00:00"
}

In this example:

The messageId uniquely identifies the current message (response-message-id-12345).
The messageReferenceId links the current message to a previously sent message (original-message-id-67890).
The messageClass identifies the current message as a response

Message Date and Expiration🔗

In the sedex system, the validity of a message is strictly determined by the messageDate specified in the sedex envelope.

Validity Duration

The validity period of a message is 31 days from the messageDate (or from the dispatch date if the messageDate is set in the future).

Expiration of a Message

A message can expire after being sent:

Seven days before the message expires, the sedex-client produces a receipt 701 Message expires soon. This allows the sender to contact the recipient through other means, such as asking them to start their sedex-Client to retrieve the message.
Once the validity period has passed, undelivered messages are considered expired.
The system will no longer deliver it to the recipient. This issue typically occurs when the recipient's sedex-Client is not running continuously.
The sender will receive an error receipt indicating that the message was not delivered but has expired with error code: 204 message expired.

If the message is already expired at the time of sending, the system will reject the message with the error code 203 too old to send.

Common Errors🔗

Invalid Envelope Schema: The sedex-Client cannot process envelopes that do not conform to the schema. Any invalid message will be rejected with status code 200 Invalid envelope syntax.
Duplicate Message ID: The sedex-Client ensures the uniqueness of the messageId. Any duplicate message will be rejected with status code 201 Duplicate message ID.

Best Practices🔗

To ensure successful message exchanges:

Always validate envelopes against the schema before sending.
Assign unique messageId values to avoid duplication.
Monitor and handle receipts to track delivery and processing statuses.