blast

Overview

Schedule a mass mail campaign, or check on the status of a previously scheduled campaign.

See also Campaign Overview.

 

Base URL

https://api.sailthru.com/blast

GET Mode

Get data on a single blast

Note: Sailthru highly encourages the use of the stats API call to retrieve blast-specific statistics.

 

Required Parameters
Parameter Description Example
blast_id blast ID 34463
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
reply_to Reply To Email Value support@sailthru.com
subject Campaign Email Subject Monday's Campaign
content_html HTML Content of the campaign <p>We wanted to bring you a holiday greeting...</p>
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
stop_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 http://blog.sailthru.com/

 

Get blast meta-data

 

Get blast status

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

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

 

Required Parameters

Only required if status=sent

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

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.

Note: 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 <p>We wanted to bring you a holiday greeting...</p>
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. Emails in the suppression list 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 http://example.com/datafeed.json
vars Key/value hash of variables to directly pass into the blast without using a data feed {"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 adFlight 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
content_app Push Notifications - The alert message or notification message that the user will receive  {"content_app":"This is the text of the push notification."}
app_badge Push Notifications - (iOS Only) The number in the corner of the application. This value can be zephyr or an integer {"app_badge":1} or {"app_badge":"{profile.vars.favorite_number}"}
app_sound Push Notifications - The sound that will play when an push notification is received (this sound must be provided by the client's app) {"app_sound":"dingding.wav"}
app_data Push Notifications - An array of key value pairs that represents the data intended to send to the app. Keys must be strings, values can be zephyr  {"app_data":{"key":"{profile.vars.value}","product_deep_link:id_12"}}
app_id Push Notifications - This is the app_id that the message is intended to go to. This app id can be found in the url of the specific app's settings page. Find your apps here. {"app_id":"536a90009dbcd4924e000251"}
Note: 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
 
Note: In order to cancel the blast, just make a POST request with schedule_time of null or empty string.

 

Examples

Example #1: Schedule a campaign to go out at 9:30 AM EST on Valentine's Day

name=2012 Valentine Mail list=main_list schedule_time=2012-02-14 9:30:00 EST from_name=Example.com from_email=noreply@sailthru.com replyto=V-Day Folks subject=Celebrate Valentine's Day content_html=<p>We wanted to bring you a Valentine's Day greetings... etc...</p> content_text=We wanted to bring you a Valentine's Day greetings... etc... is_google_analytics=1 
PHP Client equivalent
$sailthru_client->scheduleBlast(     '2012 Valentine Mail',     'main_list',     '2012-02-14 9:30:00 EST',     'Example.com',     'noreply@sailthru.com',     "Celebrate Valentine's Day",     "<p>We wanted to bring you a Valentine's Day greetings... etc...</p>",     "We wanted to bring you a Valentine's Day greetings... etc...",     array(  'replyto' => 'V-Day Folks <vday@example.com>',             'is_google_analytics' => 1));

Example #2: Schedule a campaign to generate immediately from a template data feed, then actually send in an hour

eval_template=template-name list=list-name data_feed_url=http://url/to/the/datafeed schedule_time=+1 hour 

Example #3: Schedule a campaign to send in an hour, using a template but pulling the data feed and evaluating at send time

copy_template=template-name list=list-name data_feed_url=http://url/to/the/datafeed schedule_time=+1 hour