blast

Create and schedule an email campaign, check on the status of a previously scheduled campaign, receive information about a sent campaign, or delete a currently scheduled campaign.

Base URL

https://api.sailthru.com/blast

GET Mode

Get data on a single blast

  • Sailthru recommends the stats API to retrieve blast-specific statistics.
  • To export campaign data via the API, see the job API.
  • For more information about campaigns, see Campaign Overview.

Required Parameters

Parameter Description Example
blast_id Returns blast with the specified blast ID
NOTES:

  • If you pass blast_id as a required parameter, do not pass status, since only one is required.
34463
status Returns blasts with the specified status
NOTES:

  • If you pass status as a required parameter, do not pass blast_id, since only one is required.
sent

Optional Parameters

Parameter Description Example
vars Pass 1 to return vars that have been set on this blast 1

Return Value

Will return a data structure including some or all of the following information:

Field Description Example
blast_id Blast Id 34463
name Name of the blast Monday Campaign
list List Name MondayAM-List
suppress_list Suppression List MondayPM-List
from_name From Name Value Sailthru
from_email From Email Value support@sailthru.com
replyto Reply To Email Value support@sailthru.com
subject Campaign Email Subject Monday's Campaign
content_html HTML Content of the campaign We wanted to bring you a holiday greeting...
content_text Text Content of the campaign We wanted to bring you a holiday greeting…
is_google_analytics Google Analytics Enabled / Disabled true or false
is_link_tracking Link Tracking Enabled / Disabled true or false
report_email When the blast is completed, report will be emailed to given address example@example.com or null if not given
start_time An RFC 2822 formatted date string corresponding to the time for which delivery was started Thu, 06 Jan 2014 14:50:55 -0500
end_time An RFC 2822 formatted date string corresponding to the time for which delivery was completed Thu, 06 Jan 2014 16:20:55 -0500
status Status of a blast sent or sending or scheduled
email_count The number of emails sent 19881
data_feed_url Data feed used in the campaign https://blog.sailthru.com/

Get blast meta-data

Get blast status

Parameter Description Example
status Status of a blast See below table
Status Description
draft No schedule_time
scheduled Has schedule_time but no start_time
sending Has start_time but no stop_time
sent Has a stop_time

Sent blasts will be returned in reverse chronological order. Sending and scheduled blasts will be returned in chronological order.

Optional Parameters

Parameter Description Example
list Name of a list Welcome-List
start_date Starting date for retrieving blast metadata June 11 2014
end_date Ending date for retrieving blast metadata June 17 2014

Will return an array of a data structure listed below, as well as some or all of the following:

Field Description Example
blast_id Blast Id 34463
name Name of the blast Monday Campaign
list List Name Monday-List
email_count The number of email addresses the blast was meant to be sent 21210
sent_count The number of email addresses the blast was actually sent to 21210
schedule_time An RFC 2822 formatted date string corresponding to the time for which delivery was scheduled Thu, 06 Jan 2011 14:50:55 -0500
start_time An RFC 2822 formatted date string corresponding to the time for which delivery was started Thu, 06 Jan 2011 14:50:58 -0500

POST Mode

Create, update, cancel and/or schedule a blast.

Required Parameters

These parameters are all only required if you pass a schedule_time value to schedule the blast. If you do not pass the schedule_time value, the campaign will be saved to drafts.

If you use any of the optional copy_blastcopy_template, or eval_template parameters, you do not need to pass the parameters below if the template/campaign you are copying already has them set. For example, if you are copying from a template that has content_html, you do not need to pass content_html unless you wish to override.

Parameter Description Example
name the name to give to this new blast blast-test-1
list the mailing list name to send to my-list-name
schedule_time when the blast should send. Dates in the past will be scheduled for immediate delivery. Any English textual datetime format known to PHP’s strtotime function is acceptable, such as 2012-03-18 23:57:22 UTC, now (immediate delivery), +3 hours (3 hours from now), or March 18, 9:30 EST. Be sure to specify a timezone if you use an exact time. Leave this field blank to save the campaign to drafts. 10/15/2012 3pm EST
from_name the name appearing in the “From” of the email Daily Newsletter
from_email The email address to use as the “from” – choose from any of your verified emails newsletters@example.com
subject the subject line of the email My Subject Line
content_html the HTML-format version of the email We wanted to bring you a holiday greeting...
content_text the text-format version of the email We wanted to bring you a holiday greeting...

Optional parameters

Parameter Description Example
blast_id used to make updates to a previous unsent blast rather than create a new one 639
copy_blast the blast_id of a previous blast that you wish to copy the fields of 525
copy_template the name of a template that you wish to copy the fields of. Dynamic Zephyr code will persist and be evaluated at send time for each user. my-template
eval_template the name of a template that you wish to evaluate and turn into HTML that can be edited before sending. Dynamic Zephyr code will be evaluated as static html at schedule time and be the same for every user. my-template
replyto The Reply-To header to use in the email feedback@example.com
report_email an email address to receive a short report when the blast has finished sending emailteam@example.com
is_link_tracking 1 if you want to use link-tracking rewrites in the email, 0 if not (default 0) 1
is_google_analytics 1 if you want to use automatic Google Analytics tracking, 0 if not (default 0) 1
is_public 1 if you want to have this mass mail be publicly viewable by anyone, 0 if not (default 0) 1
suppress_list The name of a suppression list to use or an array of lists. Emails in the suppression list(s) will not be emailed my-suppression-list
test_vars A JSON data structure of variables to test with using the GUI interface {"testvar":"value"}
email_hour_range The number of hours to distribute the delivery out to, using Personalized Send Time 8
data_feed_url the URL of a data feed to pull prior to sending the blast https://example.com/datafeed.json
vars Key/value hash of variables to directly pass into the blast without using a data feed
Note: When updating a blast, if a var value already exists at the blast level, you can replace it, however, submitting a new value of null (e.g. "vars":{"myvar":''}) will not modify it.
{"testvar":"value","testvar1":"value1"}
setup The Setup section, a block of Zephyr code that will run prior to any other evaluation {content = horizon_select(content, 5)}
link_params The Auto Append Link Parameters that will be added to every rewritten (tracked) link. Zephyr values with brackets should be passed as strings. This will overwrite, not add to, existing values {"foo":"bar","user_name":"{first_name}"}
ad_plan the name of an Ad Targeter Ad Plan to use with this blast Los Angeles Daily Plan
autoconvert_text Generate the content_text by doing a simple conversion on content_html 1
test_email Send a test blast to the given email address example@example.com
status The status of the email. Set this to ‘draft’ or ‘scheduled’. (‘schedule_time’ should be set when using ‘scheduled’) draft
labels Add or remove a label by setting it to integer values 1 or 0, respectively; helpful for easier sorting {"AddLabel":1,"RemoveLabel":0}
seed_emails The campaign will send to these users regardless of optout status. This is in addition to the master seed list in your account settings. marketing@example.com,joe@example.com

In order to cancel a blast, just make a POST request with schedule_time of null or empty string.

DELETE Mode

Delete a blast.

Required Parameters

Parameter Description Example
blast_id Blast Id 737373

Return Value

Field Example
blast_id 737373
ok true or 1

In order to cancel the blast, just make a POST request with schedule_time of null or empty string.

Examples

Example #1: Create and Schedule a Campaign Using an Existing Template

JSON

{
    "name" : "Re-engagement Campaign",
	"list" : "Recently Disengaged Users",
	"schedule_time" : "10/15/2012 3pm EST",
	"copy_template" : "Re-engagement Template",
	"vars" : {
		"daily_banner" : "http://www.example.com/assets/images/dailybanner.png" 
	}
}
PHP
$response = sailthru.api_post
    (
        'blast', array(
            "name" => "Re-engagement Campaign",
    		"list" => "Recently Disengaged Users",
			"schedule_time" => "10/15/2012 3pm EST",
			"copy_template" => "Re-engagement Template"
			"vars" => array(
				"daily_banner" => "http://www.example.com/assets/images/dailybanner.png" 
			)
        )
    );

$blast_id = $response["blast_id"];


Example #2: Create and Schedule a Campaign Specifying All Content and Parameters (No Template)

JSON

{
    "name" : "Re-engagement Campaign",
	"list" : "Recently Disengaged Users",
	"schedule_time" : "10/15/2012 3pm EST",
	"from_name" : "Sailthru",
	"from_email" : "example@example.com",
	"subject" : "Haven't seen you in a while!",
	"content_html" : "<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'><htm...",
	"content_text" : "We Haven't seen you in awhile. We have a great new product in stock for you, check out {content[0].title} <a href='content[0].url'>here!</a>",
	"replyto" : "feedback@example.com",
	"report_email" : "marketingteam@sailthru.com",
	"is_link_tracking" : 1,
	"is_google_analytics" : 1,
	"suppress_list" : "Optout Likely Users",
	"email_hour_range" : 8,
    "data_feed_url" : "http://feed.sailthru.com/ws/feed?id=53978fae0270838447000001",
	"vars" : {
		"daily_logo" : "http://www.example.com/assets/images/dailylogo.png" 
	},
	"setup" : "{content = horizon_select(content, 10)}",
	"link_params" : {
		"utm_campaign" : "reengagement"
	},
	"ad_plan" : "Los Angeles Daily Plan",
	"labels" : {
		"reengagement" : 1
	}
}

Top