Dynamic Recipients

Route parcelLab notifications to order-specific contacts by sending dynamic recipient roles in your tracking data and selecting those roles in Journey configuration.

Dynamic recipients let you send selected parcelLab notifications to contacts that are specific to an order or tracking, instead of only using static shop contacts or the main customer email.

This is useful for multi-party logistics flows where operational updates may need to go to a supplier, drop-shipper, 3PL warehouse, franchise store, installer, repair partner, B2B buyer contact, internal purchasing department, or gift recipient.

How Dynamic Recipients Work

Dynamic recipients connect two parts of the setup:

1. You send role-based contacts in the tracking or order data.

2. parcelLab stores those contacts on the tracking as delivery_info.additionalRecipients.

3. A Journey trigger is configured with the recipient role keys it should use.

4. When the trigger fires, parcelLab looks for matching roles on the tracking.

5. If the role exists and the email address is valid, the message is sent to that address. Missing roles, unknown roles, and invalid email addresses are ignored.

Dynamic recipients can be used together with other recipient types. For example, a Journey trigger can send to the customer and to one or more dynamic recipient roles.

Send Dynamic Recipients in the API

Use additional_recipients in the v4/track/orders payload to send the role-based contacts. The API accepts an array of recipient objects; Journey routing uses entries that provide:

Field	Type	Description
role	String	The recipient key that Journey configuration will reference.
email	String	The email address to use when the role is selected by a trigger.

For tracking-based notifications, send the dynamic recipients with the tracking that should drive the notification.

{
  "account": 1234,
  "order_number": "ORD-RETURN-2001",
  "mutations": [
    {
      "type": "add_tracking",
      "tracking": {
        "tracking_number": "RETURN-TRACKING-001",
        "courier": "dhl",
        "is_return": true,
        "additional_recipients": [
          {
            "role": "warehouseContact",
            "email": "[e-mail]"
          },
          {
            "role": "giftRecipient",
            "email": "[e-mail]"
          }
        ]
      }
    }
  ]
}

The v4 order API also exposes additional_recipients on the order payload. Use the location that matches the record used by your notification flow. If the notification is triggered by a shipment or return tracking, include the roles on that tracking.

For endpoint details, see Full Order API Spec. For the field definition, see Additional Recipients for Notifications.

Configure the Journey Trigger

After the data is available, configure the Journey trigger to use the required role keys. In Journey Manager, this is handled in the trigger configuration's advanced recipient settings. Add the same role keys that you send in additional_recipients.

For example, to send a message to the customer and the gift recipient:

{
  "Recipient": {
    "customer": true,
    "additionalRecipients": ["giftRecipient"]
  }
}

To send an operational message only to a warehouse contact:

{
  "Recipient": {
    "additionalRecipients": ["warehouseContact"]
  }
}

The role names must match exactly. If the trigger expects warehouseContact but the tracking contains warehouse_contact, the dynamic recipient will not be selected.

Example Flow

The following example shows the full flow for a gift order:

1. The order is placed by the purchaser, so recipient_email remains the purchaser email.

2. The integration sends giftRecipient in additional_recipients with the gift recipient's email address.

3. The delivery update Journey trigger is configured with additionalRecipients: ["giftRecipient"].

4. When the trigger fires, parcelLab reads delivery_info.additionalRecipients from the tracking.

5. The delivery update is sent to the gift recipient. Other purchaser-facing messages can still use the main customer recipient.

For an operational flow, use the same pattern with a role such as warehouseContact, supplierContact, returnsAgent, or another key agreed for your setup.

Behavior and Limits

• Dynamic recipients route parcelLab notifications. They do not automatically change carrier-generated notifications that use carrier-specific recipient fields.

• Dynamic recipients are selected by role. The same role key can be reused across orders while the email address can change per order or tracking.

• A trigger can reference more than one dynamic recipient role.

• Entries without a role or email address cannot be selected for sending.

• Invalid email addresses are ignored during sending.

• Missing roles are ignored, so a trigger can safely reference a role that only exists for some orders.