> For the complete documentation index, see [llms.txt](https://docs.parcellab.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.parcellab.com/docs/engage/messages-and-journeys/configuration/dynamic-recipients.md).
# Dynamic Recipients
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.
{% hint style="info" %}
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.
{% endhint %}
## 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.
```json
{
"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": "warehouse@example.com"
},
{
"role": "giftRecipient",
"email": "gift.recipient@example.com"
}
]
}
}
]
}
```
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](https://github.com/parcelLab/gitbook-documentation/tree/main/developers-v4/orders/full-order-api-spec.md). For the field definition, see [Additional Recipients for Notifications](https://github.com/parcelLab/gitbook-documentation/tree/main/developers-v4/data-elements/data-model.md#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:
```json
{
"Recipient": {
"customer": true,
"additionalRecipients": ["giftRecipient"]
}
}
```
To send an operational message only to a warehouse contact:
```json
{
"Recipient": {
"additionalRecipients": ["warehouseContact"]
}
}
```
{% hint style="warning" %}
The role names must match exactly. If the trigger expects `warehouseContact` but the tracking contains `warehouse_contact`, the dynamic recipient will not be selected.
{% endhint %}
## 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.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.parcellab.com/docs/engage/messages-and-journeys/configuration/dynamic-recipients.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.