Custom events let you track specific actions your contacts take outside of standard email engagement, things like placing an order, upgrading a plan, completing a course module, or abandoning a shopping cart. When you use a custom event as a workflow entry trigger, you can pull that event's data directly into workflow emails to create highly personalized messages.
This article walks you through setting up a workflow that triggers on a custom event and using that event's data as personalization variables inside your workflow emails.
Prerequisites
Before you can build a workflow using custom event data, two things need to be in place.
1. Custom events and properties must be created in SendX
Go to Settings > Custom Fields & Events > Custom Events and create the events your system will track. Each custom event has a name (like "order," "signup," or "purchase") and one or more properties that hold the specific data points for that event (like "order_id," "price," or "product_name").
Properties support multiple data types: Text, Number, Boolean, and Date. There's no limit to how many properties you can add per event.
2. Events must be pushed to contacts via the API
Custom events are created in the SendX UI, but the actual event data gets attached to contacts through the SendX Custom Event API. Your development team will need to set up API calls that push event data to SendX whenever the relevant action happens in your app or website.
A typical API call's data looks like this:
{
"name": "order",
"identifier": "jane@example.com",
"data": {
"order_id": "ORD-12345",
"product_name": "Yoga Mat",
"price": "45.00",
"currency": "USD"
},
"time": 1735670400
}The name matches the custom event you created in SendX. The identifier is the contact's email. The data object contains the custom event properties and their values. And time is the UNIX timestamp of when the event occurred.
For a deeper look at custom events and how to use them for segmentation, see How to Create Targeted Segments Based on User Actions with Custom Events in SendX.
Step 1: Create a New Workflow
Navigate to Automate > Workflows
Click + Create Workflow
Choose Start from scratch or select a template
Give your workflow a name (e.g., "Order Fulfilled Follow-Up")
Step 2: Set Up the Custom Event Trigger
The entry trigger is what decides which contacts enter this workflow and, importantly, which event data will be available for personalization in your emails.
Click the Trigger node on the canvas
Under Enter triggers, set the source dropdown to SendX
Choose Custom event added as the trigger type
Select the specific custom event from the dropdown (e.g., "order," "signed_up," "purchase")
At this point, the workflow will fire whenever the selected custom event is pushed to any contact via the API.
Adding Trigger Filters (Optional)
Trigger filters let you narrow down which contacts enter the workflow based on the event's property values. This is optional but very useful when you only want contacts to enter under specific conditions.
Expand the Trigger filters section
Select a property from the dropdown (these are the properties belonging to the custom event you selected above)
Choose an operator from the dropdown (contains, equals, etc.)
Enter the value to filter on
For example, if your "order" event has a property called "order_status," you could set a filter where order_status contains fulfilled. That way, only contacts whose orders have been fulfilled will enter this workflow, not contacts with pending or cancelled orders.
Note: If you set up multiple entry triggers on the same workflow, they use OR logic. A contact entering through any one of the triggers will start the workflow.
Step 3: Add an Email Step
Click the + button below the trigger to add a step
Select Email
Enter an Email name (internal reference, e.g., "Order Fulfilled")
Enter a Subject line (e.g., "Hope you are satisfied with your order")
Select a Sender
Click Edit to open the email editor
Choose a template or start from scratch, then customize your email content
This is where custom event personalization comes in. Inside the email editor, you can pull in the actual event data that triggered the workflow.
Step 4: Add Custom Event Data to Your Email
To personalize your email with data from the custom event that triggered the workflow, you type special functions directly into the content pane of the email editor. There is no variable picker for these. You type them right into the text where you want the value to appear.
The get_value Function
This function pulls a specific property value from the triggering custom event.
Syntax:
{{get_value .event "event_name.property_name"}}
Example: If your custom event is named order and it has a property called order_id, you'd write:
Your order number is: {{get_value .event "order.order_id"}}When the email is sent, this will render as something like: "Your order number is: ORD-12345"
Here's a more complete example showing multiple properties in a single email:
Hi there, Thank you for your purchase!
Order ID: {{get_value .event "order.order_id"}}
Product: {{get_value .event "order.product_name"}}
Amount: {{get_value .event "order.price"}}{{get_value .event "order.currency"}}
We hope you love it.
The get_value_with_fallback Function
Sometimes a property might not have a value for a particular contact. Maybe the data wasn't included in the API call, or the property was added after some events were already tracked. The fallback function lets you specify a default value to show instead of a blank.
Syntax:
{{get_value_with_fallback .event "event_name.property_name" "fallback_value"}}
Example:
Your coupon code: {{get_value_with_fallback .event "order.coupon_code" "No coupon applied"}}If the contact's event data includes a coupon code, it will display. If not, the email will show "No coupon applied" instead.
What Happens Without a Fallback
If you use get_value and the property doesn't exist or has no value for that contact, the email will display a dash character (-) in place of the value. If you'd rather show something more meaningful than a dash, use get_value_with_fallback.
Putting It All Together: Example Walkthrough
Let's say you're an ecommerce store and you want to send a follow-up email after an order is fulfilled.
1. Create the custom event
In Settings > Custom Fields & Events > Custom Events, create an event called order with properties like order_id, product_name, price, order_status.
2. Push event data via API
Your development team sets up an API call that fires when an order status changes to "fulfilled":
{
"name": "order",
"identifier": "customer@example.com",
"data": {
"order_id": "ORD-98765",
"product_name": "Wireless Headphones",
"price": "79.99",
"order_status": "fulfilled"
},
"time": 1735756800
}
3. Set up the workflow
Create a workflow with the trigger: SendX > Custom event added > order. Add a trigger filter: order_status contains fulfilled.
4. Build the email
Add an email step. In the email editor, write something like:
Hi there, Great news! Your order has shipped.
Order #: {{get_value .event "order.order_id"}}
Item: {{get_value .event "order.product_name"}}
Total: ${{get_value .event "order.price"}}
If you have any questions about your order, just reply to this email. Thanks for shopping with us!
5. Activate the workflow
Publish the workflow. Now, every time a contact receives an "order" event with order_status of "fulfilled," they'll enter the workflow and receive a personalized email with their specific order details.
Important Notes
Custom event personalization only works in workflow emails. Because the event data comes from the entry trigger, these functions are tied to the workflow context. They cannot be used in regular newsletter campaigns or drip campaign emails.
Property names are case-sensitive. Make sure the property names you type in the email match exactly what's defined in your custom event. If your property is called OrderId, using orderid or order_id won't work.
The event name in the function must match the custom event name. The first part of the dot notation (before the period) is your custom event name. The second part (after the period) is the property name.
You type these directly into the content. There is no dropdown or variable picker for custom event functions. You need to type the full syntax into the email content pane manually. Double-check your syntax before publishing.
Test before going live. Use the Send Test Email option in the email editor to verify that your functions are formatted correctly. Keep in mind that test emails may show placeholder values or dashes since there's no real event data being triggered.
Frequently Asked Questions
Can I use custom event data in regular campaigns or drip emails?
No. Custom event personalization is only available in workflow emails. The event data is passed from the workflow's entry trigger, which is why it only works in that context.
What data types can custom event properties hold?
Properties support Text, Number, Boolean, and Date types. There's no limit to how many properties a single custom event can have.
Where do I type the personalization functions?
Directly into the content pane of the email editor. There's no variable picker. You type the full function syntax (including the double curly braces) right where you want the value to appear in the email.
What if I misspell a property name?
The email will show a dash (-) for that value since the property won't be found. Always double-check that property names in your functions match exactly what's defined in your custom event.
Can I use trigger filters to control which contacts enter the workflow?
Yes. Trigger filters are optional but let you narrow entry based on the event's property values. For example, you can filter by order status, event source, or any other property on the custom event.
Do I need a developer to set this up?
You can create the custom events and workflow entirely within the SendX UI. However, pushing event data to contacts requires API calls, so you'll need a developer to integrate the Custom Event API with your app or website.
Can I use custom event data in workflow condition steps?
No. Custom event data can be used in the workflow entry trigger (to determine who enters) and in workflow email steps (for personalization). It's not available in condition steps within the workflow.
What if the same contact triggers the event multiple times?
Each event push can trigger a new workflow entry, depending on your workflow's re-entry settings in the Exclude Contacts section. The email personalization will always use the data from the specific event that triggered that particular workflow entry.