event

Custom events offer you the flexibility to inform the platform of any user behavior and associated data that you want to bring into the system. When called, events can initiate specific Lifecycle Optimizer flows, Smart Strategies tactics, or Triggers.

For example, you could use a custom event and associated trigger to manage user requests to add items to their Wish Lists. The event call would specify the user by email address and the product’s URL. The trigger listening for that event would add the product URL to the user’s profile as a var and add the user to a “Wish List Reminders” list. You could also set Lifecycle Optimizer to listen for the “wishlist” event and automatically schedule a follow-up email a week later, reminding the user about the item. Your custom events exist in addition to a set of system-generated events that are initiated automatically upon each transactional email’s send, or a user’s open, click, or purchase (when a purchase is attributed to a specific send). All of these events can likewise initiate Lifecycle Optimizer flows, Smart Strategies tactics, or triggers. You can submit a custom event using this event API or the customEvent JavaScript function. Note: This endpoint only accepts POST requests.

Endpoint URL: https://api.sailthru.com/event

POST

There is no need to pre-establish an event name in the system–simply submit an event by a consistent name when it occurs. No action will be taken unless another tool (Lifecycle Optimizer, Smart Strategies, or trigger) has been configured to listen for that event name. You may want to begin sending events as a first step prior to programming the actions that should be taken upon their receipt.

Examples

Submit Event

Identify user by email
{ 
   "id" : "example@example.com",
   "event" : "userPostedComment"
}
Identify user by alternate ID type
{
    id : "1234567890"
    key : "sid"
    event : "userPostedComment"
}

Submit with Vars

{
   "id" : "user@example.com",
   "event"  : "wishlist add", "vars" : {"url" : "http://example.com/123", "name" : "Widget"}
}
<!--

"Submit

<pre><code class="lang-json">{ id : "example@example.com", event : "attendingConcert", "vars" : { id : 12345678}, schedule_time : "March 1, 2017 8:00pm EST" }
–> Required Parameters
  • event – Name of the event
  • id – Email address of the user, or alternate profile key if specified by key parameter
Optional Parameters
  • vars – A hash of data to send with the event to the service listening for it
  • key – required to specify an alternate user profile key in the id parameter, other than the user’s email address
Event Name Restrictions The following event names will return an HTTP status code of 400:
  • send
  • cancel
  • open
  • click
  • purchase
  • daily
Use Custom Fields in Lifecycle Optimizer
If you include custom fields (vars) as part of an event call, those custom fields can be used in Lifecycle Optimizer flow messaging. Custom fields must be included on the Event API POST and will only be accessible to email templates sent via that specific Lifecycle Optimizer flow when the Event is the flow entry.
  1. In a Lifecycle Optimizer flow, set the Entry as Custom Event (API).
  2. Enter the same event name you used in the API and the custom fields attached to that event in the Edit Entry panel.
  3. In the template for your flow, reference the custom field using Zephyr. See the following table for an example.
Event API custom field name (key) Value Zephyr variable reference in template What will display in the message
product_rating 5 {product_rating} 5
Event vars will take priority over same-named profile custom fields. This is important to note if you use event custom fields with the same names as profile custom fields. If you use a lot of event custom fields, also note that a single event’s custom fields must be under 1 MB, which aligns with the current limitation of the /send API endpoint.

Note: Custom event vars are not accessible to Push templates the way they are to email templates. To use a custom event var with a Push template, you must first set it as a custom var on the user’s profile.

Contact us

Top