blast

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

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

To get started, use the API Client Library for your preferred language, or learn how to make Sailthru API calls with curl on the API Technical Details page. When using either method, or the API Test tool, you can use this page as a reference for building calls and interpreting responses.


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


GET Blast Data

Retrieve all information about a specific campaign, or information about all campaigns by status.

Get Blast

Example Call:
{"blast_id":"12345678"}

Get All by Status

Sent:
{"status":"sent"}
Sending:
{"status":"sending"}
Unscheduled (Drafts):
{"status":"unscheduled"}
Scheduled:
{"status":"scheduled"}
Example Response
{
    "unscheduled_count" : 62,
    "scheduled_count" : 2,
    "sending_count" : 1,
    "sent_count" : 20671,
    "blast_count" : 25737,
    "status" : "scheduled",
    "skip" : 0,
    "blasts" : [
        {
            "blast_id" : 18516531,
            "labels" : [
                "New York Office",
                "Tip Of The Day"
            ],
            "name" : "Post Blast: Subject Line Here (Final Text)",
            "subject" : "Subject Line Here",
            "list" : "Tech Notes",
            "mode" : "email",
            "data_feed_url" : "http://feed.sailthru.com/ws/feed?id=9e8a89291c086d027c000000",
            "status" : "scheduled",
            "modify_time" : "Tue, 03 Jan 2017 13:01:19 -0500",
            "schedule_time" : "Tue, 03 Jan 2017 16:00:00 -0500",
            "email_count" : 35371
        },
        {
            "blast_id" : 18516571,
            "labels" : [
                "LA Office",
                "Products"
            ],
            "name" : "Post Blast: Subject Line Here (Final Text)",
            "subject" : "Subject Line Here",
            "list" : "New Products Subscribers",
            "mode" : "email",
            "data_feed_url" : "http://feed.sailthru.com/ws/feed?id=9e8a89291c086d068c000000",
            "status" : "scheduled",
            "modify_time" : "Tue, 03 Jan 2017 13:05:09 -0500",
            "schedule_time" : "Tue, 03 Jan 2017 18:00:00 -0500",
            "email_count" : 35372
        },
    ],
    "filtered_count" : null
}

Get Status Counts

Call:
{}
Example Response:
{
    "unscheduled_count" : 18,
    "scheduled_count" : 6,
    "sending_count" : 1,
    "sent_count" : 10674,
    "blast_count" : 10699
}

Parameters

Parameter Description
blast_id Returns blast with the specified blast ID.

You must pass blast_id or status, but not both.

status Returns blasts with the specified status.

You must pass blast_id or status, but not both.

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

Blast Response Parameters

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.

Create Blast - Basic

{
    "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" 
	}
}
Uses an existing template, and sets a single blast var.

Create Blast - Advanced

{
    "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
	}
}

Uses most optional parameters, including “content_html” and “content_text” – specifying the content and code directly rather than using a template. Note that using templates is a Sailthru best practice, but your individual needs may vary.

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.

In order to cancel a blast, make a POST request with the blast_id and a schedule_time of null or empty string. (See Optional Parameters.)

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 the template’s content.

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

DELETE Blast

Delete a blast.

Note: To cancel (unschedule) a blast and keep it in the system, simply make a POST request with schedule_time of null or empty string, instead.

Required Parameters

Parameter Description Example
blast_id Blast ID 737373

Return Value

Field Example
blast_id 737373
ok true or 1
 
Top