Triggering External Events – Emarsys

Toutes nos excuses, cette page n'a pas encore été traduite. L'équipe Localization d' Emarsys est en train d'y remédier et souhaite vous proposer toute la documentation en Français!

You can use this endpoint to trigger any named External Event for a specified contact. For example, an external event can be when someone hits the I want to learn more about this product button in your webshop. When the button is clicked, this endpoint is called, triggering the Automation Center program, which sends out more information about your product.

Prerequisites

You should already have a custom field for the external ID, called externalId (if you do not have one, create it in the application via the Admin menu, Field Editor).
To create a contact with custom fields such as externalId, you need the IDs of the fields you want to involve. You can fetch them via the API (see the Listing Available Fields document in the Emarsys API documentation) or find them in the Admin menu, Field Editor.

Note:For further information about creating emails with transaction-specific content, see Creating Transactional Emails. For the list of possible campaign related placeholders, see Email Personalization Placeholders.

Endpoint

POST https://api.emarsys.net/api/v2/event/<event_id>/trigger

Parameters

Required parameters

Name	Type	Description	Comments
event_id	int	ID of the external event, which should be provided as part of the URI, as seen in the URI example above.
key_id	mixed	Key which which identifies the contacts.	You can use any field ID, id or uid here. If you identify your contact with their id or uid, you must use the string `id` or `uid` here and provide the actual id or uid in the `external_id` parameter.
external_id	string	External ID for the given field specified with field_id, id or uid.	To list the id and/or uid for any contact, use the Querying Contact Data API call.

Optional parameters

Name	Type	Description	Comments
data	string	External Data in JSON format.

Request Example

{
  "key_id": "3",
  "external_id": "t.odinson@example.com",
  "data":
  {
    "global":
    {
      "itemName": "hammer",
      "itemPrice": "123"
    }
  }
}

This request example shows that if the email template is prepared properly, the placeholders itemName and itemPrice are replaced by the values here in the email campaign which is sent to the specified contact.

Checking Results

There are two ways to check if the Automation Center program was successfully triggered:

You can check the Analysis page of the program and verify that the number of emails sent out has increased.
You can include a test customer among the contacts and check if it receives the relevant email.

Errors

HTTP Code	Reply Code	Message	Description
400	2004	Invalid key field ID: [field_id].	The field ID does not exist.
400	2005	No value provided for key field: [field_id].	The value of the key field was not provided or is empty.
400	2008	No contact found with the external ID: [key_id] – [external_id].	No match for the specified [key_id] – [external_id] pair.
400	2010	More contacts found with the external ID: [key_id] – [external_id].	More than one contact with the provided key field value exists in the database. A unique external key must be provided. Please note that using multiple identifiers is not possible via the API. If you need multiple identifiers, you need to use the Import page.
400	5001	Invalid event ID for customer.	The customer doesn’t have an external event with the specified [id].
400	2012	Invalid contact ID for customer.	The customer doesn’t have a contact with the specified [external_id].
400	5005	No program or campaign is triggered.	No active Automation Center program or email campaign is assigned for the external event.