If you want to thank contacts for their first purchase and you also want to mention the product they bought, you need to include transaction-specific content. In this case you have to use a placeholder for the transaction-specific content in your email and send the item name along with the external event.

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.

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

Create Email Content

If you include placeholders in your email campaign, you can check with the Preview function how it will look when the field referenced by the placeholder contains data.

Include Name Placeholder
  • Open the Content Creation page.
  • Edit the HTML version and put the placeholder into it, e.g.: “Hello %%name%%, have a nice day!”.
  • Save it.
  • Click Preview.
  • Click Edit placeholders.
  • Provide a name.
  • Click Refresh.

name-placeholder

You can see the preview with the field value in it. Note that you can also check the JSON content here.

Include URL Encoding Placeholder

The URL encoding placeholder is connected to the JSON field called “search” in this example: %%UrlEncode_search%%.

  • Insert a link into the content and put the URL encoding placeholder into it, e.g. http://google.com?q=%%UrlEncode_search%%.
  • Save it.
  • Provide data for “search” as described above.
  • Click the link you inserted into the email.

%%UrlEncode_search%% will be replaced with the URL encoded version of the value provided for the “search” field. It is useful when this value contains a character which must be encoded when it is designed to be used as a simple parameter in the URL (e.g. the “?” and “#” sign).

Launch Email

  • Make sure that your email is launched.

Suite_API_acivate_email_colour

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:

    {
       "3":"test@example.com"
    }

To identify the contact we are using their email address, which is also the default key. Therefore, we do not have to define a key_id here.

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.

    You can trigger your external event by sending a POST request to the /api/v2/event/<id>/trigger URI, where the <id> is your external event ID. The following example shows a minimal payload:

    {
       "key_id":"3",
       "external_id": "test@example.com"
       "data":
       {
          "global":
          {
             "itemName": "keyboard",
             "itemPrice": "123"
          }
       }
    }

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 ‘3’ meaning the e-mail address.
  • external_id = The value of the key field, the contact’s email in this case.
  • data = Your transaction-specific content in form of placeholder:value that are included in a global object.

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.