This article explains how to use custom API events to create dynamic content in your campaigns.

Ⓘ Available to Plus, HQ, Essentials, Teams, and Corporate accounts

Emma’s Event API allows you to send even more timely and personalized mailings by responding to activities that are tracked in other platforms, such as your CRM, online store, or webinar service. The data from events shared with the Event API (like product purchases, event registrations, and survey completions) can be used to trigger automated workflows, as well as to personalize your message using dynamic content.

⚠	Warning
	Like the rest of our API, the Event API is a tool generally used by programmers, so you’ll want to be familiar and comfortable with this type of work before moving forward.

 

	In This Article
	Personalization Tags Dynamic Content Nested Attributes Using Items Left in an Abandoned Cart Additional Resources

Personalization Tags

Personalization with custom API events works similarly to standard personalization. The key difference between personalization based on contact information and personalization based on event attributes shared via the event API is a simple formatting distinction. Contact field personalization tags use the prefix member, while event personalization tags use the prefix event. For example:

Personalization Type	Format
Contact field personalization	[% member:city %]
Event personalization	[% event:purchase_amount %]

 

Finally, personalization based on event attributes does not use default values. In contact field personalization, you can include a default value for the tag to display if that field is empty for a recipient - for example, [% member:city default="Boston" %]. However, event personalization is not compatible with a default value.

Personalization for nested attributes is more complex, please see below for details.

Dynamic Content

Similar to regular dynamic content, you can use the event personalization tags and conditional logic to control a campaign's contents based on the data from an API event. For example, if you have an API event for a survey completion, the message in the campaign can be altered slightly based on whether a customer indicates that they are satisfied or not.

In the example below, the name of the survey is written as survey_name in the event. For this survey, a reply of 7 or higher is considered satisfied, while a reply of 6 or less is considered not satisfied. The results of a customer's satisfaction are shared in the value for the key overall_satisfaction. Here's how the content for this will look in the campaign editor:

Thank you for taking our [% event:survey_name %]!

 

[% if event:overall_satisfaction > “6” %]

 

Please don’t ever hesitate to get in touch if there’s something you’d like to see from us!

 

[% elif event:overall_satisfaction < “7” %]

 

We never want you to be anything less than thrilled with our service, and we want to make things right. Please call us at 555.555.5555 if there’s anything at all that we can do to make things better for you.

 

[% endif %]

Nested Attributes

Not all data from API events will be neatly paired into top-level key / value pairs. Some event data is nested, meaning that one attribute (such as line_items in an order completed from an ecommerce platform) contains multiple related attributes (such as the item IDs, names, prices, and other related attributes). Here is an example of the line_items data from such an order:

{
  "event_name": "order-completed",
  "id": 1028374857,
  "email": "test@test.com",
  "closed_at": null,
  "created_at": "2016-04-12T11:00:00-09:00",
  "total_price": "145.53",
  "total_discounts": "14.70",
  "order_number": 1001,
  "discount_codes": [
    {  
    "code": "TEN16",
      "amount": "10.00",
      "type": "percentage"
    }
  ],
  "line_items": [
    {
      "id": 998327818,
      "variant_id": 59284621,
      "title": "Slim Short Sleeve Linen Shirt",
      "quantity": 1,
      "price": "68.00",
      "sku": "SLSSLNSHRT",
      "variant_title": "white",
      "size": "medium",
      "product_id": 632910392,
      "requires_shipping": true,
      "taxable": true,
      "gift_card": false,
      "name": "Slim Short Sleeve Linen Shirt - White",
      "tax_lines": [
        {
          "title": "State Tax",
          "price": "6.12",
          "rate": 0.09
        }
      ]
    },
    {
      "id": 789327523,
      "variant_id": 89137513,
      "title": "Slim Mens Chino",
      "quantity": 1,
      "price": "79.00",
      "sku": "SLMNCHNO",
      "variant_title": "green",
      "size": "32W32L",
      "product_id": 948517351,
      "requires_shipping": true,
      "taxable": true,
      "gift_card": false,
      "name": "Slim Mens Chino - Green",
      "tax_lines": [
        {
          "title": "State Tax",
          "price": "7.11",
          "rate": 0.09
        }
      ]
    },
    "shipping_lines": [
      {
        "id": 0928273492,
        "title": "Free Shipping",
        "price": "0.00",
        "code": "Free Shipping",
        "source": "shopify",
        "phone": null,
        "carrier_identifier": null,
        "tax_lines": [
        ]
      }
    ]
  ]
}

Using Nested Attributes to Inform Content

It’s common for marketers to want to use line items from an order and other nested sets of data in the content of their emails. This could be used to tell your contacts what they may have left in their cart or to ask them to leave reviews on items that were purchased in a completed order, etc. This is possible using dynamic content with an operator known as a "for loop".

A for loop tells Emma to look (or “loop”) over the individual attributes contained within a set of similar items (such as line_items in the above example) and to insert a piece of content into the campaign for every item found within the set.

For Loop Example

Let’s say that we want to insert a piece of content that includes the title, quantity, and price of all items in an order. It’s likely that this order contains multiple items, so we want them all to appear within the email, one after the other.

Using a for loop operator tells Emma that we want to search the event data for a specific attribute (line_items in this case) and identify all nested attributes of that parent attribute as something consistent (we’ll say item here). Then, Emma can use the attributes of that item to personalize the message. So the snippet below would produce a series of product descriptions (quantity, item title, and price).

[% foreach context:event:line_items as item %]
[% context:item:quantity %], [% context:item:title %], [% context:item:price %]
[% endforeach %]

✎	Note
	The context tag cannot be used for personalization outside of a for loop or a length value tag.

Using Items Left in an Abandoned Cart

In addition to showing all items in an order or other list, it’s possible to dynamically include the number of items in that list. For example, if you wanted to send an abandoned cart message that told users how many items had been left in their cart, you could do so using the following snippet:

[% length value=[% context:event:line_items %] %]

This gets really interesting if you want to show different messages based on how many items appear in a list. For this, you’d format your message differently based on whether a customer had abandoned one item in their cart or multiple items. For example, this snippet will display the text “Did you forget something?” if a customer has left more than one item in their cart.

[% if [% length value=[% context:event:line_items %] %] > “1” %] Did you forget something? [% endif %]

Additional Resources

• API Documentation
• Event API Documentation
• Event API: Overview
• How to Add Personalization to Drag and Drop Campaigns
• How to Add Personalization to Legacy Campaigns
• How to Use the Automation Workflow Builder
• Trigger Events: Custom API Event