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.
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
}

Blast Parameters

Parameter Description
blast_id Returns blast with the specified blast ID.You must pass either blast_id or status, but not both.
status Returns blasts with the specified status. Specify one of the following values:
  • created - blasts with no schedule_time
  • scheduled - blasts with schedule_time but no start_time
  • sending - blasts with start_time but no stop_time
  • sent - blasts with a stop_time
Note: Sent blasts will be returned in reverse chronological order. Sending and scheduled blasts will be returned in chronological order. You must pass either blast_id or status, but not both.
vars Pass 1 to return vars that have been set on this blast

Optional Filter Parameters when Requesting by Status

Parameter Description Example
limit The maximum number of blasts to return. Set to 0 to get all results. If not specified, the default maximum of 20 blasts is used. 0
skip Use in conjunction with limit to paginate results. For example, you could set your limit to 10, then increment your skip with each call to receive the next 10 results until you reach the count for that status--the total number of available results--which is returned with each call. (See Response Parameters.) 1
list Name of a list Welcome-List
start_date Starting date for retrieving blast metadata. If the time is not specified for this parameter, midnight will be used as the default. June 11 2014 or 2020-05-21 12:00 AM EST
end_date Ending date for retrieving blast metadata. If the time is not specified for this parameter, midnight will be used as the default. June 17 2014 or 2020-05-28 11:59 PM EST

Response Parameters for Individual Blast

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 Your Name
from_email From Email Value support@example.com
replyto Reply To Email Value support@example.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
labels Array of labels used to categorize the campaign. ["spring","marketing"]
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.example.com/
modify_user The email address of the user who last modified the campaign. If no modify_user is present, the campaign was last modified via API. user@example.com
modify_time The timestamp of the last time the campaign was modified/saved. Fri, 13 Apr 2018 09:23:42 -0400

Response Parameters for Blasts by Status

FieldDescriptionExample
blast_id Blast Id 34463
labels Array of labels used to categorize the campaign. ["spring","marketing"]
name Name of the blast Monday Campaign
list List Name Monday-List
mode The sending mode. Can be:
  • sms 
  • visual email (an email composer template)
  • email (an HTML template)
"mode" : "sms"
stats Statistics for a sent message. See the stats documentation for the blast parameters. "stats" : { "total" : { "count" : 1 } },
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" : "Your Name",
    "from_email" : "example@example.com",
    "subject" : "Haven't seen you in a while!",
    "content_html" : "<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 best practice, but your individual needs may vary.

Create Blast - Retargeting

{
  "name" : "Re-engagement Campaign",
  "from_name": "Your Name",
  "from_email": "example@example.com",
  "subject": "Test send",
  "content_text": "Hello World",
  "previous_blast_id" : "18870377",
  "message_criteria":  "not_opened",
  "schedule_time" : "02/13/2020 12pm EST",
  "copy_template" : "New Template from December 3, 2019, 1:02:29 PM"
}
Uses an existing template to retarget a campaign.

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. 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 will start to send. Required for:
  • schedule_type: "specific"
  • schedule_type: "personalized"
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. When a timezone is not provided, the account timezone will be used. Note: If you wish to send a blast immediately, use "now".
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. Note: content_html can be used with or without content_text. Both parameters are required, but they are not required to be used together. We wanted to bring you a holiday greeting...
content_text The text-format version of the email. Note: content_text can be used with or without content_html. Both parameters are required, but they are not required to be used together. We wanted to bring you a holiday greeting...
message_criteria Use when creating a retargeting campaign. These are the criteria used to select the users to retarget. "message_criteria": "not_opened"
previous_blast_id Use when creating a retargeting campaign. The ID of the blast campaign you are retargeting. 18870377
schedule_type How to send the blast Options
  • specific
Send the blast at the time specified in schedule_time.
  • personalized
Send the blast at the optimal time for each recipient within the window given in email_hour_range starting at the time specified in schedule_time. See Personalized Send Time
  • local_timezone
Send the blast to each recipient in their local timezone, as specified by the  local_day and local_time fields. See Local Send Time
specific
local_day The day to send the blast in the Local Send Time in the format YYYY-MM-DD. Required for:
  • schedule_type: "local_timezone"
2021-10-30
local_time The time to send the blast in the Local Send Time in a 24-hour format of HH:SS Required for:
  • schedule_type: "local_timezone"
13:00

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. Note: The setup parameter will override template content if you are creating a blast with a template. {content = horizon_select(content, 5)}
link_domain Defines the link domain to be used. This is only relevant when an account has more than one domain. link.test.com
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 Whether the blast should be sent. If this parameter is not provided, it will be set to draft. Options
  • draft
The blast is a work in progress and will not be sent.
  • scheduled
The blast will be sent according to its schedule_type. Automatically updated statuses:
  • sending
The blast is in the process of being sent.
  • sent
The blast is finished being sent.
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 main seed list in your account settings. The seed email list allows the following formats:
  • Newline delimited string
  • Comma delimited string (shown)
  • An array of strings
marketing@example.com,joe@example.com

DELETE Blast

Delete a Blast

{
 "blast_id":"12345678",
 "schedule_time":""
}
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

Contact us

Top