Prepare Your First Message

This section explains how to prepare message content and envelope files before submitting a delivery to the Digital Postbox Platform.

Messages are prepared by creating one or more envelope files and preparing the referenced body and attachment files.

After preparation, files can be submitted using one of two methods:

• S3 Upload Method: upload envelopes and referenced files to an S3-compatible storage service before creating a delivery
• Direct Multipart Submission: submit envelopes and referenced files directly in a multipart request

Each envelope defines:

• Sender identity
• Recipient identification
• Message content
• Optional message features
• Delivery metadata

For S3 Upload Method, all envelopes and referenced files must be available in storage before creating a delivery.

To prepare a message for delivery, you must:

1. Create one or more envelope files
2. Prepare message body and attachments
3. Upload all files to storage
4. Verify envelope references
5. Validate recipient identification

Each envelope represents one logical message.

Multiple envelopes may be submitted in a single delivery.

An envelope is a JSON document that describes a message.

It specifies:

• Who sends the message
• Who receives the message
• Which files are delivered
• Which features apply

Envelopes must conform to the platform envelope schema.

Each envelope must have a unique messageId within the sender organisation.

Recipients are identified using identity attributes provided by approved identity providers.

Each recipient must include an identity object with exactly one key-value pair, where the key is the identity type and the value is the recipient's identifier.

Example:

{
  "identity": {
    "NationalId": "1234567890"
  }
}

Supported identifiers may include:

• National identifiers
• Organization identifiers
• User identifiers
• Email address
• Mobile number

Identity requirements depend on sender permissions.

An envelope may contain up to ten recipients.

Delivery behavior is atomic:

• All recipients receive the message
• Or no recipients receive the message

If any recipient is invalid, unsubscribed, or unavailable, the envelope is rejected.

Messages may be scheduled for future delivery.

Use the deliverAt field:

{
  "deliverAt": "2026-03-01T08:00:00Z"
}

The value must follow RFC 3339 format.

If omitted, delivery occurs immediately.

Senders may require recipients to accept that an open receipt will be sent before accessing the content.

{
  "requireOpenReceipt": true
}

Restrictions:

• Only supported for single-recipient envelopes
• One receipt is registered per message

Opening receipts can be retrieved from the administrative portal or via the APIs.

If a recipient does not have an account, messages are normally rejected.

The interim repository allows temporary storage per recipient.

Example:

{
  "identity": {
    "NationalId": "1234567890"
  },
  "interim": {
    "enable": true,
    "notificationEmail": "recipient@example.com"
  }
}

Behavior:

• Message is stored temporarily
• Recipient is notified
• Delivery occurs after account creation

Undelivered messages are purged after the retention period.

Message files can be encrypted before upload. Encryption is optional but recommended when the sender requires additional control over confidentiality.

When encryption is used:

• The same encryption key must be used for all files within the same delivery
• The encryption key must be recorded by the sender
• The encryption key must be provided when calling Create Delivery
• If the provided key does not match the encrypted content, the delivery will fail during validation

Supported encryption modes:

• AES 256 CBC
• AES 256 GCM, not yet supported and planned for near-term release

AES 256 GCM will be the recommended mode once available, as it provides authenticated encryption and built-in integrity protection.

When using CBC mode:

• CBC does not include data integrity checks
• Corruption in encrypted data or an incorrect key will not be detected automatically
• It is important to include a content hash in the envelope so the platform can verify that the decrypted content matches the expected content

For detailed encoding formats and reference implementations, see Encryption during delivery.

Platform-enforced limits for deliveries using the S3 Upload Method:

Size limits for deliveries using Direct Multipart Submission:

Files exceeding limits are rejected during validation.

Envelopes may optionally include a cryptographic hash string for referenced files.

If provided, the platform validates the file content against the supplied hash before processing.

Hash verification is recommended when:

• Client-side encryption is used
• Files are transferred across multiple systems
• Data integrity must be verified

Files may include an optional hash string for integrity validation.

Example:

{
  "body": {
    "name": "refinancing-appointment-2020-01-07.rtf",
    "mimeType": "text/rtf",
    "filename": "refinancing-appointment.rtf",
    "hash": "<HASH_VALUE_HERE>"
  }
}

Hashes are recommended when using CBC encryption.

This example sends an invoice document to one recipient.

Invoice file:

invoice-880942299.pdf

Sender:

senderId: 3
organizationId: 6

Recipient:

Identity value: Hugo
Identity type: Username

Save as:

invoice-880942299.json

{
  "messageId": "invoice-880942299",
  "title": "Invoice",
  "sender": {
    "senderId": 3,
    "organizationId": 6
  },
  "recipients": [
    {
      "identity": {
        "Username": "Hugo"
      }
    }
  ],
  "body": {
    "name": "invoice-880942299.pdf",
    "mimeType": "application/pdf",
    "filename": "invoice.pdf"
  }
}

Be aware that the envelope name must be the same as the messageId + .json.

This example sends an appointment confirmation with an attachment.

Message file:

refinancing-appointment-2020-01-07.rtf

Attachment file:

refinancing-appointment-2020-01-07.pdf

Sender:

senderId: 5
organizationId: 8

Recipients:

Vigo
Alma

Save as:

refinancing-appointment-2020-01-07T11:45:00.000Z.json

{
  "messageId": "refinancing-appointment-2020-01-07T11:45:00.000Z",
  "title": "Refinancing discussion",
  "sender": {
    "senderId": 5,
    "organizationId": 8
  },
  "recipients": [
    {
      "identity": {
        "Username": "Vigo"
      }
    },
    {
      "identity": {
        "Username": "Alma"
      }
    }
  ],
  "body": {
    "name": "refinancing-appointment-2020-01-07.rtf",
    "title": "Refinancing",
    "mimeType": "text/rtf",
    "filename": "refinancing-appointment.rtf"
  },
  "attachments": [
    {
      "name": "refinancing-appointment-2020-01-07.pdf",
      "title": "Refinancing appointment",
      "mimeType": "application/pdf",
      "filename": "refinancing-appointment.pdf"
    }
  ]
}

Before creating a delivery, verify:

• All referenced files exist in storage
• All envelope filenames match uploaded objects
• All messageId values are unique
• Recipient identities are valid
• Optional features are supported
• Encryption keys are available if used

Validation failures are reported in delivery reports.

After preparing envelopes and content:

• Choose a Submission Method
• Upload Content to S3
• Send Messages via Multipart
• Verify and Troubleshoot