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.