# Trigger Messages

## Trigger Message

Details of how the `trigger-message` endpoint can be used to manually trigger emails configured in the parcelLab system are described below.

<details>

<summary><mark style="color:green;">POST</mark> Trigger Message</summary>

You can manually trigger an email that has been configured in parcelLab using the `trigger-message` endpoint.

To use this API, you need your parcelLab `user_id` and `API token` for authentication.

The details of the Trigger Message API are described in the following section.

**API Details**

<mark style="color:green;">`POST`</mark> `https://api.parcellab.com/v2/trigger-message`

**Header**

| Name                                           | Type   | Description          |
| ---------------------------------------------- | ------ | -------------------- |
| user<mark style="color:red;">\*</mark>         | number | parcelLab user ID    |
| token<mark style="color:red;">\*</mark>        | string | parcelLab API token  |
| content-type<mark style="color:red;">\*</mark> | string | `'application/json'` |

**Request Body**

| Name                                      | Type   | Description                                                                                                                           |
| ----------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| to<mark style="color:red;">\*</mark>      | array  | List of recipients for the notification consisting of `address` and `name`.                                                           |
| client                                    | string | Client ID as set in parcelLab. This can be omitted if no multi-client account has been set up.                                        |
| locale                                    | string | Locale as Java locale format (for example: `en` or `de_DE`). If left empty, will first default to client configuration, then `en_US`. |
| channel<mark style="color:red;">\*</mark> | string | Message channel that has to be active on account (for example: `email`, `SMS`).                                                       |
| message<mark style="color:red;">\*</mark> | string | Message ID as set in parcelLab.                                                                                                       |
| placeholders                              | array  | Any custom placeholders to be used within the template as defined in the format specified below.                                      |
| delay                                     | number | Number of seconds to delay email sending by                                                                                           |
| correlationId                             | string | Any unique correlation ID that will be returned in the feedback webhook. If not set, will be generated.                               |

**Responses**

* 202 - email has been triggered and will be sent, you are returned a correlationId to reference result webhooks
* 400 - the provided payload is invalid and could not be accepted, the error will list details about the issue of the payload
* 403 - no or invalid credentials provided
* 500 - request returned an error, please reach out to <support@parcellab.com> with the error reference

An example request is displayed below to show the format for triggering a message.

{% code title="sample-request.sh" %}

```bash
curl --request POST 'https://api.parcellab.com/v2/trigger' \
--header 'user: 1612197' \
--header 'token: token-with-write-scope' \
--header 'Content-Type: application/json' \
--data-raw '{
    "to": [
        { "address": "abc@parcellab.com", "name": "Customer Name" },
        { "address": "xyz@parcellab.com" }
    ],
    "client": "parcelFashion",
    "locale": "en",
    "channel": "Mail",
    "message": "WarehouseNotification",
    "placeholders": [
    ],
    "delay": 60,
    "correlationId": "5ee80bba-7bb9-4427-a32f-5b374e39a1de"
}'
```

{% endcode %}

</details>

### Recipients

The recipients are defined in the `to` array as an array of objects.

The recipient values are described in the following table.

| Key       | Value                                                                                            | Type     | Required? |
| --------- | ------------------------------------------------------------------------------------------------ | -------- | --------- |
| `address` | Recipient email address, or phone number, or recipient ID for alternative notification channels. | `string` | Yes       |
| `name`    | Clear name of the recipient.                                                                     | `string` | No        |

### Placeholders

You can provide `placeholders` in the API call.

The `placeholders` key is an array of objects with two fields, one defining the name of the placeholder and one the value. The name must be identical to the placeholder used in the message.

{% hint style="info" %}
The key and placeholder name will show as custom fields when placeholders are sent via the API call (for example: `{key/customField}` and `{placeholder name/customField}`).
{% endhint %}

The placeholder values are described in the following table.

| Key     | Value                                                                                                | Type                       | Required? |
| ------- | ---------------------------------------------------------------------------------------------------- | -------------------------- | --------- |
| `name`  | The name of the placeholder to be used in the message.                                               | `string`                   | Yes       |
| `value` | The actual content of the placeholder, can be text, number, or boolean for conditional placeholders. | `string`, `number`, `bool` | Yes       |

## Re-trigger Message

Details of how the `re-trigger-message` endpoint can be used to re-trigger emails sent in the parcelLab system are described below.

<details>

<summary><mark style="color:yellow;">PUT</mark> Re-trigger Message</summary>

You can re-trigger an email that has been sent using the `re-trigger-message` endpoint.

To use this API, you need your parcelLab `user_id` and `API token` for authentication and the channel and message ID must be given in the payload.

The details of the Re-Trigger Message API are described in the following section.

**API Details**

<mark style="color:yellow;">`PUT`</mark> `https://api.parcellab.com/v2/re-trigger-message`

**Header**

| Name                                           | Type   | Description          |
| ---------------------------------------------- | ------ | -------------------- |
| user<mark style="color:red;">\*</mark>         | number | parcelLab user ID    |
| token<mark style="color:red;">\*</mark>        | string | parcelLab API token  |
| content-type<mark style="color:red;">\*</mark> | string | `'application/json'` |

**Request Body**

| Name                                      | Type   | Description                                                   |
| ----------------------------------------- | ------ | ------------------------------------------------------------- |
| channel<mark style="color:red;">\*</mark> | string | Type of message to re-trigger (for example:. `email`, `SMS`). |
| id<mark style="color:red;">\*</mark>      | string | ID of the message to re-trigger as retrieved from our API.    |

**Responses**

* 202 - accepted: re-trigger accepted
* 400 - bad request: channel or ID not given/valid
* 401 - unauthorized: credentials not correct
* 404 - not found: channel/ID combination not found
* 500 - internal server error: re-trigger of message failed

An example request is displayed below to show the format for re-triggering a message.

```shell
curl --request PUT 'https://api.parcellab.com/v2/re-trigger-message' \
--header 'user: 1612197' \
--header 'token: token-with-write-scope' \
--header 'Content-Type: application/json' \
--data-raw '{
    "channel": "Mail",
    "id": "50ae00000000000000000001"
}'
```

</details>

## Feedback via Webhook

Our system will notify about sending the result asynchronously via webhook, if the webhook has been set up in the system. One webhook receiver can be defined by `client`.

The feedback webhook includes the following:

#### `correlationId`

The `correlationId` that was either given in the request, or returned as part of the request by our API. If no `correlationId` has been given in the request, our system will generate a [UUID v4](https://en.wikipedia.org/wiki/Universally_unique_identifier) and return it.

#### `result`

The result of email delivery, which can either be success or bounce.

{% tabs %}
{% tab title="Successful  Delivery" %}

```javascript
{
    "correlationId": "5ee80bba-7bb9-4427-a32f-5b374e39a1de",
    "success": true
}
```

{% endtab %}

{% tab title="Delivery Failed" %}

```bash
{
    "correlationId": "5ee80bba-7bb9-4427-a32f-5b374e39a1de",
    "success": false,
    "failure": "Permanent / General"
}
```

For emails, the `failure` will be one of the bounce types.

{% content-ref url="/spaces/-LPf1Lv1YUuLYva6LrXQ/pages/-Li4NjNlVKFnfeNKwzSu" %}
[Bounces](/docs/engage/messages-and-journeys/configuration/bounces.md)
{% endcontent-ref %}
{% endtab %}
{% endtabs %}

The webhook setup is identical to the status data feedback.

{% content-ref url="/pages/GBBllcv2aH16J29bRrsp" %}
[Webhooks](/docs/developers/v2/data-elements/get-status-updates/webhooks.md)
{% endcontent-ref %}


---

# Agent Instructions: 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:

```
GET https://docs.parcellab.com/docs/developers/v2/orders/trigger-messages.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.