- Getting Started
- API Home
- API Postbacks
- API Response Errors
- API Technical Details
- Client API Libraries
- HTTP Response Codes
- Email & User Profiles
- blast
- blast_repeat
- list
- send
- template
- user
- Reporting
- job
- stats
- Horizon
- content
- purchase
- Advanced & Beta Features
- ad/plan
- alert
- preview
- settings
- trigger
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/blastGET 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 | Monday-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 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 | praj@sailthru.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 2012 14:50:55 -0500 |
| end_time | An RFC 2822 formatted date string corresponding to the time for which delivery was completed | Thu, 06 Jan 2012 16:20:55 -0500 |
| status | Status of a blast | sent or sending or scheduled |
| hardbounce_total | Hard Bounce total | 10 |
| softbounce_total | Soft Bounce total | 17 |
| delivered_total | Delivered total | 2418 |
| open_total | How many users opened the campaign | 2245 |
| click_total | How many users actually clicked the campaign | 2130 |
| optout_total | Total Opt-outs | 21 |
| spam_total | Marked as spam | 5 |
| public_url | If the campaign is marked as 'public', will return the publicly accessible url. Read more here. | link.mydomain.com/public/1526469 |
| vars | Vars set on the blast, only returned if the vars parameter is used |
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 2012 |
| end_date | Ending date for retrieving blast metadata | June 17 2012 |
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_blast, copy_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 |
| abtest |
1 if you want to create a new A/B test. You should also pass a blast_id and a test_percent. A new A/B test for that blast_id will be created, populating the new test with all the rest of your POSTed data. Repeat as needed to create A/B/Final segments. |
"abtest":1,"blast_id":"123456","test_percent":"10" |
| test_percent | the percent of emails in the list that this test should apply to (just pass an integer number; the % sign is not necessary) | 15 |
| 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)} |
| 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 |
Note: In order to cancel a blast, just make a POST request with schedule_time of null or empty string.
DELETE Mode
Create, update, cancel and/or schedule a blast.
Required Parameters
| Parameter | Description | Example |
|---|---|---|
| blast_id | Blast Id | 737373 |
Return Value
| Field | Example |
|---|---|
| blast_id | 737373 |
| ok | true or 1 |
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 | my-template |
| eval_template | the name of a template that you wish to evaluate and turn into HTML that can be edited before sending | 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 |
| abtest | 1 if you want to create a new A/B test. You should also pass a blast_id and a test_percent. A new A/B test for that blast_id will be created, populating the new test with all the rest of your POSTed data. | 1 |
| test_percent | the percent of emails in the list that this test should apply to (just pass an integer number; the % sign is not necessary) | 15 |
| 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)} |
| 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 |
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