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:

Copy

{"blast_id":"12345678"}

Get All by Status

Sent:

Copy

{"status" : "sent"}

Sending:

Copy

{"status" : "sending"}

Unscheduled (Drafts):

Copy

{"status" : "unscheduled"}

Scheduled:

Copy

{"status" : "scheduled"}

Example Response

Copy

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

Copy

{}

Example Response

Copy

{
    "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`
`open_total`	The unique opens for a campaign.	`114396`

Response Parameters for Blasts by Status

Field	Description	Example
`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

Uses an existing template, and sets a single blast var.

Copy

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

Create Blast - Advanced

Copy

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

Copy

{
  "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_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 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 inschedule_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 theLocal 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

Copy

{"blast_id":"12345678",
 "schedule_time":""}

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