The simplest way to send a welcome mail is to use the default value for the “where to?” parameter, which is the contact’s email address.

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

Launch Email

  • Make sure that your email is launched.

Step 1: Create the contact

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.

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":"3",
       "external_id": "test@example.com"
    }

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 email address.
  • external_id = The value of the key field, the contact’s email in this case.

Note:

  • 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.