Recipient Identification

Recipient identification defines how a message is linked to one or more receivers in the Digital Post Platform.

Before a message can be delivered, each recipient specified in an envelope must be resolved to a valid mailbox and verified against platform rules.

This section explains how recipients are identified, validated, and resolved during delivery processing.

Each envelope contains one or more recipient definitions.

For each recipient, the platform must be able to:

• Identify the receiver
• Locate the associated mailbox
• Verify subscription status
• Verify account eligibility
• Apply delivery rules

If any recipient cannot be resolved, the entire envelope is rejected.

Partial delivery is not permitted.

A receiver represents the end user that receives digital messages.

Receivers:

• Are not part of the organisational hierarchy
• May receive messages from multiple sender identities
• Interact with messages through a mailbox
• Are resolved during delivery processing

Each receiver is associated with exactly one mailbox per platform instance.

Recipients are defined in the envelope using the recipients field.

Each entry contains 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 structure:

{
  "recipients": [
    {
      "identity": {
        "NationalId": "123456789"
      }
    }
  ]
}

Each envelope must contain at least one recipient.

An envelope may contain up to ten recipients.

The primary method of recipient identification is identity based lookup.

Each recipient is identified using a single key-value pair on the identity object:

• The key represents the identity type (e.g. NationalId, Username)
• The value is the unique identifier issued by the identity provider

Example:

{
  "identity": {
    "NationalId": "123456789"
  }
}

The available identity types are defined by the platform configuration.

Integrators must use the correct identity type and format for each market.

An envelope may include multiple recipients.

Example:

{
  "recipients": [
    {
      "identity": {
        "Username": "Vigo"
      }
    },
    {
      "identity": {
   "Username": "Alma"
  }
    }
  ]
}

Multi-recipient envelopes follow atomic delivery rules:

• All recipients must be valid
• All must be subscribed
• All must pass validation

If any recipient fails validation, the entire envelope fails.

Before delivery, the platform verifies that each recipient is subscribed to the sender identity.

Subscription verification ensures that:

• The receiver has accepted communication
• Delivery complies with platform rules
• Sender policies are enforced

If a recipient is not subscribed, delivery fails.

If a recipient does not yet have an active account, delivery is normally rejected.

The interim repository allows temporary storage for such recipients.

Interim storage is configured per recipient in the envelope:

{
  "identity": {
    "NationalId": "123456789"
  },
  "interim": {
    "enable": true,
    "notificationEmail": "user@example.com"
  }
}

When enabled:

• The message is stored temporarily
• The recipient is notified via the provided email
• Delivery completes after account activation

If interim storage is not enabled and the recipient has no account, delivery fails.

During delivery processing, recipients are resolved in the following sequence:

1. Identity format validation
2. Identity provider lookup
3. Mailbox resolution
4. Subscription verification
5. Account eligibility checks
6. Interim repository evaluation

Only when all steps succeed does delivery proceed.

Recipient resolution may fail for several reasons.

Failure details are reported in the delivery report logs array. Each entry includes a key that identifies the failure type.

The following keys are related to recipient resolution:

Other delivery-level failures that may affect envelope processing include:

For the full list of delivery report keys, see Verify and Troubleshoot.

Failure details are recorded in the delivery report.

Recipient resolution directly affects delivery outcomes.

If resolution fails:

• The envelope is rejected
• No recipients receive the message
• The failure is logged
• The delivery report is updated

Other envelopes in the same delivery may continue processing.

Before sending production messages, integrators should verify recipient eligibility.

Recommended practices:

• Validate identity formats
• Test subscriptions
• Use lookup APIs when available
• Verify interim repository behavior
• Monitor delivery reports

Testing reduces failed deliveries and operational overhead.

Recipient identification depends on:

• Sender Configuration
• Subscription Management
• Authentication

It directly influences:

• Delivery Model
• Message Lifecycle
• Reporting and Billing

Understanding recipient identification is required before implementing message submission.

For more information, see:

• Message Delivery Model
• Message Lifecycle
• Getting Started Guides
• Delivery API Reference
• Sender API Reference