Trigger Messages

Use our API to manually trigger the sending of transactional emails that have been templated and set up before, or to re-trigger messages that have already been sent.

Trigger Message

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

POST Trigger Message

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

POST https://api.parcellab.com/v2/trigger-message

Header

Name	Type	Description
user*	number	parcelLab user ID
token*	string	parcelLab API token
content-type*	string	'application/json'

Request Body

Name	Type	Description
to*	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*	string	Message channel that has to be active on account (for example: email, SMS).
message*	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 [email protected] with the error reference

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

sample-request.sh

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": "[email protected]", "name": "Customer Name" },
        { "address": "[email protected]" }
    ],
    "client": "parcelFashion",
    "locale": "en",
    "channel": "Mail",
    "message": "WarehouseNotification",
    "placeholders": [
    ],
    "delay": 60,
    "correlationId": "5ee80bba-7bb9-4427-a32f-5b374e39a1de"
}'

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.

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}).

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.

PUT Re-trigger Message

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

PUT https://api.parcellab.com/v2/re-trigger-message

Header

Name	Type	Description
user*	number	parcelLab user ID
token*	string	parcelLab API token
content-type*	string	'application/json'

Request Body

Name	Type	Description
channel*	string	Type of message to re-trigger (for example:. email, SMS).
id*	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.

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"
}'

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 and return it.

result

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

Successful Delivery

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

Delivery Failed

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

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

BouncesBounced messages are automatically monitored by our systems. You can be informed of bounces by webhook or via a scheduled export.

The webhook setup is identical to the status data feedback.

Webhooks