If you want to use the same ID that you have in your external database to identify contacts in the Emarsys application, you can use an external ID.

Let’s suppose that external ID is the name of the column in your database that contains the external ID and you want to use the same name for your custom field in the Emarsys application.

Preparation

Preconditions

To perform these preparatory steps you will need the credentials for your Emarsys account (account name and environment, user name and password).

Note: Create a dedicated external event for each of your emails, otherwise a single external event may accidentally trigger many emails.

  1. 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.
  2. Fetch the field ID of the externalID field.

Note: To create a contact with custom fields like our externalID you need the IDs of the fields you want to involve. You can fetch them via the API (see the Listing Field Lists chapter in the Emarsys API Technical Reference).

Create an external event

  • Create the external event in the Emarsys UI. You can find external events in the Automation menu.

Suite_API_create_external_event

Email Settings

  • Create the email:
    • Set Generated through an event as the Recipient source.
    • Set On External Event as the Event.
  • Choose your event

Suite_API_set_external_event_as_recipient_source

Launch Email

  • Make sure that your email is launched.

Step 1: Create user

To create a new contact, send a POST request to the <a class="external text" href="http://dev.emarsys.com/suite/contacts/contact_create.html" rel="nofollow" target="_blank">/api/v2/contact</a> URI.

The following example shows a minimal payload:

    {
       "key_id":"123456",
       "123456":"789",
       "3":"test@example.com"
    }

To identify the contact we are using the key id of the externalID field you figured out during the preparation step.

Note: You cannot create an already existing contact.

For further information about creating a contact in the Emarsys application, see Creating a Contact in the Emarsys API Technical Reference.

For further information about updating a contact in the Emarsys application, see Updating a Contact in the Emarsys API Technical Reference.

Step 2: Trigger the event

Preconditions
  • You need at least one contact available in the Emarsys application so that the contact data can be used.

Trigger your external event by sending a POST request to the /api/v2/event/<id>/trigger URI. Use your external event ID as the id. For more about the external ID, see below.

The following example shows a minimal payload:

    {
       "key_id":"123456",
       "external_id": "789"
    }

Where…

  • id = The external event ID (not the name!). Since these IDs don’t change, you can just use the API demo page to get the ID, and use it in your integration script.
  • key_id = The ID of the key field of the contact. We are using the key id of the externalID field you identified during the preparation step.
  • external_id = The value of the key field, your ‘external ID’ in this case.

Notes:

  • Retrieve external event IDs by querying all external events on the API (see the Querying External Events chapter in the Emarsys API Technical Reference).
  • For further information about triggering external events, see the chapter Triggering External Events in the Emarsys API Technical Reference.
  • For a list of available Field IDs, click here.

Step 3: Check results

Check Sent-Counter
  • Check whether an email was sent successfully:
    • Check with a test contact if the ‘Welcome email’ has arrived; it should be delivered within seconds.
    • Use the Emarsys UI to check if an email was sent. In the Analysis module in the Emails page you can see that the count of Sent emails increases.