Overview

The event data collection, which is referred to as contactactivites in the database, contains behavioral data records for all contacts in the system. These include reserved message events, system events, and custom-named events associated with website behavior such as browse, order, and cart activity. The event data collection also contains external events captured by IoT devices such as opened door or triggered alarm.

Each event is associated to a contact using the contact's primary or secondary identifier. You can leverage this data to to personalize message content, build audiences, trigger messages, and build analytics reports. For a complete list of events supported by Cordial, visit our system events reference page.

Reserved message events

• message-sent
• open
• click
• optout
• bounce
• complaint
• message-stopped

How Cordial stores events

The following is an example of JSON-formatted event data stored in the contact activities collection. This example shows three events associated with the same contact:

• A browse event
• A message sent
• A message open

The events associated with a message contain additional information about the message. The browse event shows additional information about the product that was browsed, like title and price.

[
   {
    "cID": "58c6dae96e05abd5fef72184",
    "_id": "58c7170250c860b711c3af04",
    "properties": {
      "category": "Shirts",
      "url": "http://cordial.io/demo",
      "description": "Really cool shirt.",
      "price": 10.5,
      "title": "Red Shirt"
    },
    "action": "browse",
    "time": "2025-03-13T22:02:42+0000",
    "email": "fredgarvin@example.com"
  },
  {
    "cID": "58c6dae96e05abd5fef72184",
    "mcID": "45:dfd5c31449b9fb9f42da7bb0a79f94ee:d170313:58c6dae96e05abd5fef72184:1489445319",
    "mdtID": "56e85788733462ca899bc891",
    "_id": "58c721c867b929236e8b4567",
    "action": "message-sent",
    "time": "2025-03-13T22:48:40+0000",
    "bmID": "45:dfd5c31449b9fb9f42da7bb0a79f94ee:d170313",
    "email": "fredgarvin@example.com",
    "properties": {
      "stp": "dyn"
    }
  },
  {
    "cID": "58c6dae96e05abd5fef72184",
    "mdtID": "58c839b36e05abd5fefc63aa",
    "mcID": "45:f2a318f9a064d93760c4beaa39970d72:d170323:58c6dae96e05abd5fef72184:1490308322",
    "first": true,
    "_id": "58d44d7d5c90d40c7992ca66",
    "action": "open",
    "time": "2025-03-23T22:34:37+0000",
    "bmID": "45:f2a318f9a064d93760c4beaa39970d72:d170323",
    "email": "fredgarvin@example.com"
  }
]

Available events

Message events

Message event data like send, open, click, and bounce is created and stored automatically in the Cordial system when a message event takes place.

Message events are inherently system-generated events associated with message sending activity.

System events

Similar to message events, these events are predefined and capture corresponding activities as they happen. System events have a crdl_ prefix. You can view the available system events on our system events reference page.

Custom events

Custom events are created by you according to your marketing strategies and business needs.

Use case

In order to send your subscribers a cart abandonment message, you need to create a custom-named event like cart to be used as a trigger to send an email when a contact adds an item to their cart. In this scenario, you would likely create another custom event called order that would be used to cancel the cart abandonment message if the customer completes the purchase.

• Learn how to create a cart abandonment message here.

Track browse behavior

You can also create custom-named events to track browse behavior on your website. Browse events can be used to trigger a browse abandon message when a contact leaves your site without purchasing anything. This is only one of many possibilities. 

• Learn how to create a browse abandon message here.

The sky is the limit with custom events

There are countless opportunities to trigger personalized messages based on custom events. Custom events can be created for when a contact views a video, downloads a file, or likes an article. This is just the tip of the iceberg. Custom events can also be created based on IoT behaviors such as triggering an alarm, opening a door, and many others. The options are limitless. 

Regardless of the event name, all custom events are passed to Cordial using JavaScript Listeners embedded on your site, or via an API call. Custom events contain the name of the event (such as browse, cart, or order) as well as the optional properties associated with that event such as a URL, images, or descriptions.

The default maximum number of properties an event can have is 1,000.

• Learn more about passing custom-named event data using JavaScript Listeners here.
• Learn more about passing custom-named event data using API calls here.

View custom events

1. Navigate to Data > Custom Events to view the custom events you've created in Cordial.

2. Click an event to view it in JSON format.

3. You can also view event data via API by making an API call to view all events or filtered events.

• Learn more about viewing event data using API calls here.

Event Data Reports

To visualize event data in a chart, navigate to Analytics > Event Data Reports. Flter the report results by event type, contacts, audience rules, and date ranges.

• Learn more about Event Data Reports here.

Export events

You can export event data by creating a Data Job in the UI or using an API call.

Export events via UI

1. Log in to Cordial and navigate to Data Jobs > Create New Data Job.

2. Under Export, select Events.

3. Fill in the Name and Tags fields. For Type, choose either One-time or Recurring. Assign a Priority for the job and click Continue.

4. From the Data Job page, click Edit in the Data Source pane.

5. In the Events pane, configure the events you'd like to export: specify the actual Event (opens, clicks, opt out, message sent, or any other system event), Contacts who triggered the event, and the Date range for when the event was triggered.

• The example below shows configuration for all batch messages that were opened by people in their 30s within the past day.

You can export data for multiple events.

6. Select Edit under Data Mapping and enter the required fields:

• Export file name: give your file a unique name.
• Export file type: choose CSV or JSONL.
• Column key(s): Select or manually enter the list and attribute keys you want to use to map the data in your export.

  Some list and attribute keys, such as time, action, and email, will automatically show up when you click the dropdown arrow. You can also manually type in keys such as mcID, msID, message_name, and more—as long as they align with the schema of the event data you're exporting (opens, clicks, etc.).

• Check the Header box to include a header row in your exported file.
• Select whether to Compress file(s) or Split file per chunks. If splitting the file, specify the amount of records to appear in each file.

7. Select Edit under Data Destination and choose the destination for your exported events file. You can select Local, FTP, SFTP, AWS S3 bucket, Google Cloud, or Azure Blob.

This method of exporting events automatically prepares that data for the destination you specify above, so you don't need to run an additional data transformation.

8. In the On Completion pane, enter an email address where you'd like to receive a notification once the job is complete. This step is optional.

9. If your Data Job is recurring, Publish the Data Job then select Recurring under Settings on the left. From here, set the Schedule for your data job and then Enable it.

10. Run the export events Data Job. Once completed, you can find the job under the Jobs widget.

Export events via API

• Learn about exporting event data using the Contact Activity Export API here.

Use events in message content

You can personalize message content based on a contact's event behavior using the Smarty getEventRecords method. With Smarty, you can query event data per contact, filter and sort records, and then display the event and its associated properties in a message.

Use case

Personalizing message content based on event behavior is useful in browse abandon campaigns where a contact viewed items on your website but didn't add anything to the cart or make a purchase. You could trigger a message with a browse event and display the last items they browsed in the message.

• Learn more about rendering event data in a message using Smarty here.

Build audiences using events

Using the Audience Builder, you can create audiences based on message events and custom-named events.

1. Navigate to Contacts > Audience and edit or create a new audience.

2. Select System events from the Rules dropdown in the Audience Builder.

3. Click on the events you want to use and drag them into your audience.

Use case

You can combine audience rules to create complex queries such as: Show me all women who browsed a specific product (shown as browseProduct below) in the last 2 days and opened any message in the past fifteen days.

• You can learn more about the Audience Builder here.

Trigger messages with events

Using message automations, you can trigger message sends based on custom-named events. 

1. Select or create a message automation: Automations > Create New Automation. 

2. In the message creation dashboard, navigate to Sending Methods > Event Triggered in the left sidebar.

3. From the Trigger Events pane, choose the desired trigger event: 

• When a change is made to a contact attribute value
• When a contact is added to a list
• When a change is made to a contact attribute supplement record
• When an order is created or updated
• A contact's real-time behavior
  • System events
  • Custom events

Contact your CSM to enable supplement, order, and system triggers in your account. Custom event triggers are enabled by default.

Use case

If you have a custom event called browseProduct, you could trigger a message when that event is passed to your account.

• Learn more about automated messages here.

Trigger messages when an order is created or updated

You can trigger messages when orders are created or updated. For example, you could trigger a message based on an order's status changing from shipped to delivered.

1. In the Trigger Events pane, select When an order is created or updated for the Trigger event.

2. Select the Trigger strategy you want to use:

• Trigger when an order is created or updated
• Trigger only when an order is updated (ignore new orders)
• Trigger only when an order is created (ignore existing orders)

3. Under Changed field, select the event change that will trigger the message, such as when an order's delivery status changes. 

4. Add a Conditional filter as needed. 

5. Set the Delay, select whether to Enable quiet hours, and configure How often can this message be sent to an individual.

The $triggerData utility contains both old and new order data, which you can differentiate in Smarty to display additional changes.

Create analytics reports using events

System and custom-named events can be visualized over time using event dashboards. You can create event data reports for viewing and exporting all events as a report. You can also view audience populations based on events with Audience Trends reports.

Audience Trends reports

To access Audience Trends reports, log in to Cordial and navigate to Analytics > Audience Trends. From here, you can view the population of an audience over time, based on events such as website browse activity.

Use case

You can create an audience of contacts that have browsed a specific category (such as shirts in the example below), save the audience with Audience Trend analytics enabled, and then view the population over time using the Audience Trends chart.

Event dashboards

Event dashboards provide a way to create multiple charts of time-based event activity. This allows you to compare contact behaviors on your website with message activity, providing a holistic view of your marketing performance.

To create an event chart, navigate to Analytics > Event Dashboards and select Add Chart.

Use case

You could create a series of charts that visualize website browse activity for multiple product categories.

Event data reports

You can generate a report of all events passed to your account on the event data reports page—navigation: Analytics > Event Data Reports. This provides you with a log of all events in chronological order. You can filter the event report by event type, contact, audience, and date range, and you can download the report to your local computer or a remote server.

In the next article, you can learn about products.