event

What is a trigger?

A trigger is a script describing what action should be taken given the occurrence of an event.  There are two categories of events that are currently available.


Message Events

Message events: System events relating to a Sailthru message (i.e. an email).  These events fire under the following situations:

  • Send: Message is sent.
  • Click: A link is clicked from a sent message.
  • Open: The beacon image is rendered in a sent message.
  • Purchase: A purchase API call is made identifying a sent message as a referrer.
  • Cancel: A message in the act of sending encounters the zephyr condition {cancel(true)} or {assert(false)} causing the send to be aborted.
  • Custom events: May be any event that has relevance in your application.  These are fired using the “event” API.  Message event names are disallowed.

The primary purpose of a trigger script is to update a user’s profile, send emails, and/or fire off custom events.  These are achieved using the zephyr api call methods api_user, api_send,  and api_event, respectively.  Each of these methods in effect perform POST action operations to their respective API endpoints.  Each is capable of accepting an object containing the parameters to be used for the api call.

Examples:

Send template ‘bar’ with vars
{
	api_send(
		{
			'template':'bar',
			'vars':
				{
					'Hello':'World'
				}
		}
	)
}
Send using schedule_time, limit parameters, and this event’s vars
{
	params={}
}
{
	params.schedule_time = "tomorrow 9:00"
}
{
	params.template = "discount A"
}
Send only if another coupon hasn’t sent within 10 days
{
	params.limit = 
		{
			"name":"coupon",
			"within_time":"10 days"
		}
}
{
	params.vars = event.vars
}
{
	api_send(params)
}
Add user to a list
{
	api_user(
		{
			'lists':[
				'name_of_list':1
			]
		}
	)
}
Set a user’s var ‘foo’ to 1
{
	api_user(
		{
			'vars':
				{
					'foo':1
				}
		}
	)
}
Push a new value onto a user’s foo array
{if !foo} {foo=[]} {/if}{* initialize if currently empty *}
{
	api_user(
		{
			'vars':
				{'foo': 
					(
						foo + list(event.vars.foo
						)
					) 
				}
		}
	)
}
Fire off an event (see Event API later in this document)
{
	api_event(
		{
			'event':'foobar'
		}
	)
}

Message Event Triggers (a.k.a. Template Triggers)

(See also the API trigger call)

Message events locates trigger scripts that are listening to its event name and the template that was used to send the message.  This process takes place at the time of the event occurrence.

Triggers are created in Sailthru using the “trigger” API.  To create a trigger in Sailthru that will listen to message events, the name of the event type (i.e. “click”) and the template used for sending the messages should be identified.  The template(s) that a trigger should listen for may be identified either by the template’s name or by a tag that is attached to it.

Examples:

Send foo after bar is sent
apiPost(
	"trigger", 
		{    
   			"event" : "send",    
   			"template" : "bar",    
   			"zephyr" : "{api_send({'template':'foo'})}" 
   		}
 )
Send foo after a marketing template is
sent apiPost(
	"trigger", 
		{    
   			"event" : "send",    
   			"template_tag" : "marketing",    
   			//coming soon    
   			"zephyr" : "{api_send({'template':'foo'})}" 
   		}
   )

It is also possible to specify a time offset from the event that the trigger script should be executed.  This is specified using a relative time expression evaluated using PHP’s strtotime() function.  This gives you the flexibility for time offsets such as “next Thursday 9:00″, “now”, “+5 days”.  For example:

Send foo one day and 6 hours after bar is sent
apiPost(
	"trigger", 
		{    
   			"event" : "send",    
   			"time" : "+1 day 6 hours",    
   			"template" : "bar",    
  			"zephyr" : "{api_send({'template':'foo'})}" 
  		}
)
Update an existing trigger

To update an existing trigger, you may specify its trigger_idtemplate and optionally any fields that you would like to override the existing value of.

apiPost("trigger", 
	{    
   		"trigger_id : "abc123",    
   		"template" : "bar",    
   		"zephyr" : "{api_send({'template':'foo'})}" 
   	}
)
Delete an existing trigger

To delete a trigger, you may pass a delete action specifying its trigger_id and template.

apiDelete("trigger", 
	{    
   		"trigger_id" : "abc123",    
   		"template" : "bar" 
   	}
)
Retrieve stored triggers

To retrieve stored triggers for a given template, you may pass a get action specifying the template.

apiGet("trigger", 
	{    
   		"template" : "bar" 
   	}
)

Custom Event Triggers (a.k.a. Event API Triggers)

Triggers that listen for custom events are added, updated, retrieved, and deleted in the same manner as template triggers.  The only difference is that the template parameter is required to be omitted to access them.

Examples:

Create a trigger that will send a reminder email one day before a concert
apiPost("trigger", 
	{    
   		"event" : "will_attend_concert",    
   		"time" : "-1 day",    
   		"zephyr" : "{api_send({'template':'reminder','vars':event.vars})}" 
   	}
)
Update trigger zephyr for trigger_id of abc123
apiPost("trigger", 
	{    
   		"trigger_id" : "abc123",    
   		"zephyr" : "{api_send({'template':'foo'})}" 
   	}
)
Delete trigger with trigger_id of abc123
apiDelete("trigger", 
	{    
   		"trigger_id" : "abc123" 
   	}
)
Get custom event triggers
apiGet("trigger", {})

Event API

Custom events are fired by calling the “event” API.  A trigger listening to this event does not need to necessarily exist for events to be passed.  Many times the most efficient workflow is to pass all events that occur first with any potentially relevant data.  At a later time triggers can be put into place to harness the events that are being passed.

The minimum required parameters of an event are the name of the event and the id of the user.  You can optionally use a different ids by specifying the key parameter (this works the same as the user API call.

Examples:

Identifies that event foobar just occurred for ben@sailthru.com
apiPost("event", 
	{    
   		"event" : "foobar",    
   		"id" : "support@sailthru.com" 
   	}
)
Identifies that event foobar just occurred for user extid = abc123
apiPost("event", 
	{    
   		"event" : "foobar",    
   		"id" : "abc123",    
   		"key" : "extid" 
   	}
)

Optionally, you can pass along any arbitrary JSON map of vars that might be useful later.

Identifies that event ‘concert_attended’ occurred for support@sailthru.com
apiPost(
	"event", 
		{    
   			"event" : "concert_attended",    
   			"id" : "support@sailthru.com",    
   			"vars" : 
   				{         
      					"performer" : "The Zephyrs",         
      					"venue" : "Madison Square Garden"     
      				} 
      		}
)

Optionally, you may also identify a time in the future that an event will definitely occur.

Identifies that will_attend_concert happens on 3/1/2013 for support@sailthru.com
apiPost("event", 
	{    
   		"event" : "will_attend_concert",    
   		"id" : "support@sailthru.com",    
   		"schedule_time" : "March 1, 2013 9:00pm EST",    
   		"vars" : 
   			{        
      				"performer" : "The Zephyrs",        
      				"venue" : "Madison Square Garden"     
			} 
	}
)

Bulk events

See the job api call for more information. It is possible to fire events for multiple users at once identified by:

  • a) a query that will be run against existing users
  • b) a list of email addresses
  • c) a json file of user updates

Events can be fired for all matching users by specifying them in the job API call under the update[events] parameter.

Examples:

Fire event attended_concert for all emails provided
apiPost("job", 
	{    
   		"job" : "update",    
   		"emails" : "support@sailthru.com,support+2@sailthru.com,support+3@sailthru.com",    
   		"update" : 
   			{        
      				"events" : [             
      					{                
      						"event" : "attended_concert",                
      						"vars" : 
      							{                    
         							"performer" : "The Zephyrs",                    
         							"venue" : "Madison Square Garden"                 
         						}             
         				}         
         			]     
         		} 
         }
)

If a json file of updates is passed, events may be directly fired for users in bulk.  If there is a globally applied event update with the same name as an event individually specified for a user, then the vars are merged.  This allows for the ability to apply vars for an event that can be applied to all users, but still allows for flexibility to override and/or add additional vars at the user level.

Fire event attended_concert for all emails provided
apiPost("job", 
	{    
   		"job" : "update",    
   		"file" : "updates.json",    
   		"update" : 
   			{        
      				"events" : [             
      					{                
         					"event" : "attended_concert",                
         					"vars" : {                    
            						"performer" : "The Zephyrs",                    
            						"venue" : "Madison Square Garden",                    
            						"section" : "general seating"                 
            					}             
            				}         
            			]     
            		} 
            }
)
updates.json
{
	"email":"support@sailthru.com",
	"events":[
		{
			"event":"attended_concert",
			"vars":
				{
					"vip" : true,
					"section":"front row"
				}
		}
	]
} 
{
	"email":"support+2@sailthru.com",
	"events":[
		{
			"event":"foo"
		}
	]
} 
{
	"email":"support+3@sailthru.com"
}
Results in the following events being fired
{
	"id":"support@sailthru.com"
	"event":"attended_concert",
	"vars":{
		"performer" : "The Zephyrs",
		"venue" : "Madison Square Garden",
		"section":"front row",
	"vip" : true 
	} 
}	
{
	"id":"support+2@sailthru.com"
	"event":"attended_concert",
	"vars":{
		"performer" : "The Zephyrs",
		"venue" : "Madison Square Garden",
		"section":"general" 
	} 
}
{
	"id":"support+2@sailthru.com"
	"event":"foo" 
}
{
	"id":"support+3@sailthru.com"
	"event":"attended_concert",
	"vars":{
		"performer" : "The Zephyrs",
		"venue" : "Madison Square Garden",
	"section":"general" 
	} 
} 

Base URL

https://api.sailthru.com/event

Top