job

Welcome to our updated API documentation! (Details here.)
We invite you to rate this page at the bottom or send feedback to docs@sailthru.com.

Introduction

Start a background job, such as a data import or export, or get its status or result.

Jobs are asynchronous: depending on their size, they may take minutes or hours to run. Using a job POST call returns a job_id. Using a job_id in a GET call, you can request the status of the posted job. In your POST call, you can also include a report email address and/or an API postback URL to be notified when the job is complete.

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/job

Job Types

The following jobs are available.

  • blast_query – Export a csv of campaign recipients, including their profile ID, hashed email address, and open/click data.
  • blast_save_list – Query your users that received a specific campaign, and save that new segment to a new or existing natural list.
  • blast_snapshot – Query your users to see who received a specific campaign, and generate a detailed snapshot of their analytics (similar to the Snapshot Report in the Sailthru interface).
  • content_update – Create or Update content from a JSON file.
  • delete_content – Remove content from your Sailthru Content Library in bulk. This is helpful if there are pages within your content that were unintentionally or incorrectly spidered. You can delete all content or only expired content. In both cases you can narrow the selection to only delete content published during a specified date range.
  • export_list_data – Export all the users from a list including their data in CSV format.
  • export_purchase_log – Export a chronological record of purchases in CSV format.
  • export_scheduled_sends – Download a CSV report of all currently-scheduled transactional sends.
  • import – Import a number of email addresses into a natural list.
  • list_erase – Delete one or more lists by name.
  • snapshot – Query your users and generate a detailed snapshot of their analytics (similar to the Snapshot Report in the Sailthru interface).
  • update – Perform a bulk update of any number of user profiles. You can use this to generate a list for any user matching a query, opt out a large list of email addresses, add a variable to a group of users, and more.
  • purchase_import – Updates historical purchase data

You’ll specify one of the above as the  job  parameter. Each job requires and supports its own set of additional parameters.

In addition, there are two optional parameters for receiving job POST call results:

  • report_email – An email address to receive job-completion results. It is recommended that you include this with all requests, and consider using an alias for a group/distribution list that would alert multiple users within your company to any issues or errors.
  • postback_url – A URL that receives a job-completion results (i.e. the same data from a job GET call), with two additional parameters that are provided by Sailthru – your api_key and the unique  sig for the request, so that the it can optionally be verified as a legitimate Sailthru request.

How it Works

When you submit a POST to the job API, you are making a request for a job to be undertaken. These jobs are not instantaneous and are submitted to a job queue for processing. Thus, the response from a job POST will usually contain an initial status of “pending” along with a job_id and an automatically generated name for the job.

{
    "job_id" : "582e31cd3c8aa9d6278b4567",
    "name" : "List Import: empty list",
    "status" : "pending"
}

You can use the GET call (see below) to obtain an update on the status, as shown below in the example response. If the job has not yet commenced execution, the status will still be listed as “pending”.  A job that begun execution is show with a “running” status, and a completed job is shown as “completed”. For example:

{
   "_id" : ObjectId('4fc7f24a6a44a14b0b0001f1'),
   "class" : "Sail_Job_ListErase",
   "client_id" : 3386,
   "create_time" : new Date('Thu, May 31 2016, 6:35 pm EDT'),
   "create_user" : "example@sailthru.com",
   "job_id" : null,
   "list" : "Sample List",
   "postback_url" : null,
   "queue_time" : new Date('Thu, May 31 2016, 6:35 pm EDT'),
   "remove_count" : 1,
   "report_email" : null,
   "start_time" : new Date('Thu, May 31 2016, 6:36 pm EDT'),
   "stop_time" : new Date('Thu, May 31 2016, 6:36 pm EDT'),
   "time" : 0,
   "status" : "completed"
}

For export jobs, this completed response will include a filename parameter and an export_url that you can use to retrieve the requested CSV file.

If a job terminates without successful completion it will have the status “incomplete”.

Due to this behavior, the responses documented on this page will be those containing the completed status, not the immediately returned pending status.

Universal Job Parameters

GET Mode

Required Parameters

Parameter Description
job_id A job’s unique identification

Response Parameters

Parameter Description
status A job’s status: completed, pending, or error
name A job’s name
start_time A job’s start date and time; this field may not be available if job has not started
end_time A job’s end date and time; this field will not be available if job is not completed

POST Mode

Required Parameters

Parameter Description
job Job type. (See Job Parameter Value table.)

Optional Parameters

Parameter Description
report_email Email that receives a short report upon job completion
postback_url A URL that receives a job-completion results (i.e. the same data from a job GET call), with two additional parameters: api_key and sig, so that the request can be optionally verified as a legitimate Sailthru request

Job Parameter Values

Submit one as the job value to indicate the job type. Then, include the additional parameters required by that job type.

Value Description Additional Parameters for Job Type
ad_inventory Review your available Audience Builder advanced inventory over a date range. Parameters
blast_query Export list of campaign recipients data in CSV format. Parameters
blast_save_list Query your users that received a specific campaign, and save that new segment to a new or existing natural list. Parameters
blast_snapshot Query your users to see who received a specific campaign, and generate a detailed snapshot of their analytics (similar to the Snapshot Report in the Sailthru interface). Parameters
content_update Create or Update content from a JSON file. Parameters
export_list_data Export user data from a list in CSV format. Parameters
export_purchase_log Export user data from a list in CSV format. Parameters
export_scheduled_sends Download a CSV report of all currently-scheduled transactional sends. No additional parameters are required N/A
import Import a number of email addresses into a natural list. Parameters
list_erase Delete one or more lists by name. Format:{ "job" : "list_erase", "lists" : [ "list1 name", "list2 name" ] }If a list is being used for a scheduled or sending campaign, it will not be deleted. The job report will show all lists that were successfully deleted, not deleted because they were in use, and not deleted because there was no matching list name. N/A
purchase_import Update historical purchase data. Parameters
snapshot Query your users and generate a detailed snapshot of their analytics (similar to the Snapshot Report in the Sailthru interface). Parameters
update Perform a bulk update of any number of user profiles. You can use this to generate a list for any user matching a query, opt out a large list of email addresses, add a variable to a group of users, and more.

  • If you want to apply the same update to all of the users specified, you should pass the update parameter.
  • You must pass one of the required parameters, but not more than one: emails, url, file, or query
Parameters

 

Job-Specifc Parameters

blast_query

Example Call

{
   "job":"blast_query",
   "blast_id":"8305513"
}

Example Response

{
    "job_id" : "584848516e4adcbb238b46e8",
    "name" : "Export Mass Mail Data",
    "status" : "completed",
    "start_time" : "Wed, 07 Dec 2016 12:35:14 -0500",
    "end_time" : "Wed, 07 Dec 2016 12:35:25 -0500",
    "filename" : "export-blast-8305513.csv",
    "export_url" : "https://s3.amazonaws.com/sailthru/export/2016/12/07/a3ba0404814dbfa76fb24c6c99111111",
    "blast_id" : 8305513
}
Type Parameter Description Example
Required for job type blast_id A valid blast identification Example
Return for job type export_url A URL pointing to the exported data. The link expires after 24 hours.

  • The exported URL contains PII hashed data for users’ email addresses. Extid values are unencrypted. To obtain unencrypted email addresses, perform an export in my.sailthru with SMS verification.
  • For export jobs, export_url will return if the job is completed and not expired. If the job is expired, expired field with value true will return.
Example
Return for job type filename The generated file name Example

 

blast_save_list

Example - Minimum Parameters

Example Call

{
    "job":"blast_save_list",
    "blast_id":123456,
    "query":
        {
            "source_list":"Main",
            "criteria":["engagement_min"],
            "engagement":[5]
        },
     "list":"Opened-Jun-15-Campaign"
}

Example Response

{
    "job_id" : "58484c9fe661f072558b47fa",
    "name" : "Opened-Jun-15-Campaign",
    "status" : "completed",
    "start_time" : "Wed, 07 Dec 2016 12:53:36 -0500",
    "end_time" : "Wed, 07 Dec 2016 12:53:36 -0500"
}

Example - Additional Parameters

Example Call

{
    "job":"blast_save_list",
    "blast_id":123456,
    "query":
        {
            "source_list":"Main",
            "criteria":["engagement_min"],
            "engagement":[5]
        },
     "list":"Opened-Jun-15-Campaign"
     "report_email":"example@sailthru.com"
}

Example Response

{
    "job_id" : "5848501ce661f094558b4aa6",
    "name" : "Opened-Jun-15-Campaign",
    "report_email" : "example@sailthru.com",
    "status" : "completed",
    "start_time" : "Wed, 07 Dec 2016 13:08:31 -0500",
    "end_time" : "Wed, 07 Dec 2016 13:08:31 -0500"
}
Type Parameter Description Example
Required for job blast_id Identification of the blast you wish to take a snapshot of Example
Required for job query A query or search
Queries In The API
Example
Required for job list The name of the list to add users to (if it does not exist, it will be created)

  • Querying a list is not required, since you are already querying the blast itself
Example
Optional for job report_email Receive an email notification when a job is complete
job Examples
Example

 

blast_snapshot

Example

Example Call

{
    "job":"blast_snapshot",
    "query":
        {
            "source_list":"Main",
            "criteria":["engagement_min"],
            "engagement":[5]
        },
    "blast_id":"190940"
}
Show Example Response
{
    "job_id" : "5848546e15dd9634628b473e",
    "name" : "Campaign Snapshot: Sample Campaign, Campaign recipients: engagement level is at least active",
    "status" : "completed",
    "start_time" : "Wed, 07 Dec 2016 13:26:56 -0500",
    "end_time" : "Wed, 07 Dec 2016 13:26:57 -0500",
    "total" : {
        "count" : 3
    },
    "engagement" : {
        "new" : {
            "count" : 3,
            "name" : "new"
        }
    },
    "domain" : [
        {
            "count" : 3,
            "name" : "sailthru.com"
        }
    ],
    "device" : [],
    "signup" : {
        "201606" : {
            "count" : 3,
            "name" : "201606"
        }
    },
    "subject" : [
        {
            "count" : 3,
            "name" : "asdf"
        }
    ],
    "smtp" : [
        {
            "count" : 2,
            "name" : "nj1-mta-1.flt"
        },
        {
            "count" : 1,
            "name" : "nj1-mta-18.flt"
        }
    ],
    "click_times" : [],
    "click_total_times" : [],
    "beacon_times" : [],
    "beacon_total_times" : [],
    "purchase_times" : [],
    "clickmap" : [],
    "urls" : [],
    "topusers" : [
        {
            "email" : "user1@sailthru.com",
            "click_url" : null,
            "click_total" : 0,
            "open_total" : 0,
            "click_time" : null,
            "open_time" : null,
            "pv" : null,
            "rev" : 0,
            "score" : 0
        },
        {
            "email" : "user2@sailthru.com",
            "click_url" : null,
            "click_total" : 0,
            "open_total" : 0,
            "click_time" : null,
            "open_time" : null,
            "pv" : null,
            "rev" : 0,
            "score" : 0
        },
        {
            "email" : "user3@sailthru.com",
            "click_url" : null,
            "click_total" : 0,
            "open_total" : 0,
            "click_time" : null,
            "open_time" : null,
            "pv" : null,
            "rev" : 0,
            "score" : 0
        }
    ],
    "banners" : [],
    "purchase_items" : [],
    "groups" : []
}
Type Parameter Description Example
Required for job query A query or search
Queries In The API
Example
Required for job blast_id A valid blast identification Example
Return for job stats Data structure containing the results of the snapshot N/A

 

content_update

Example Call

{
    "job":"content_update",
    "file":"/tmp/file.txt"
}

Example Response

{
    "job_id" : "5848632be9328bab2a8b482b",
    "name" : "Content Update",
    "status" : "completed",
    "start_time" : "Wed, 07 Dec 2016 14:29:52 -0500",
    "end_time" : "Wed, 07 Dec 2016 14:29:52 -0500",
    "invalid_count" : 0,
    "successful_count" : 3
}
Type Parameter Description Example
Required for job file Text file with one JSON object per line, each representing a valid Content API call. Each line requires a URL. All optional parameters are supported, including inventory. Example

 

delete_content

Delete All

{
 "job" : "delete_content",
 "type" : "all"
}

Delete All Expired

Delete all expired content:

{
 "job" : "delete_content",
 "type" : "expired"
}

Delete All in Range

Delete all content published in the last 6 months of 2016 including on the specified dates:

{
 "job" : "delete_content",
 "type" : "all",
 "start_date" : "July 1, 2016",
 "end_date" : "Dec 31, 2016"
}

Delete Expired in Range

Delete only expired content published in the last 6 months of 2016 including the specified dates:

{
 "job" : "delete_content",
 "type" : "expired",
 "start_date" : "2016-07-01",
 "end_date" : "2016-12-31"
}
Type Parameter Description Example
Required for job type all to delete all content, expired to delete only expired content. Example
Optional for job start_date To constrain deleted content to a date range (by publish date) you must specify both a start_date and an end_date. Content published on the specified start_date and end_date is included in the range. Compatible formats include Month DD, YYYY and YYYY-MM-DD. Example
 Optional for job end_date To constrain deleted content to a date range (by publish date) you must specify both a start_date and an end_date. Content published on the specified start_date and end_date is included in the range. Compatible formats include Month DD, YYYY and YYYY-MM-DD.

 

export_purchase_log

Type Parameter Description Example
Required for job start_date Purchase report’s start date

  • start_date and end_date‘s format: yyyymmdd. Example: 20150115
  • The range between start_date and end_date cannot exceed 31 days
Example
Required for job end_date Purchase report’s end date Example

 

export_list_data

Example - Min. Parameters

To request only default fields.

{
"job": "export_list_data",
"list": "example list"  
}

Example with Optional Fields & SHA256 Hashing

This example requests some of the optional user fields and requests that user email addresses are hashed with the SHA256 algorithm.

{
   "job" : "export_list_data",
   "list" : "example list",
   "hash_algo" : "sha256",
   "fields" : {
       "geolocation_city" : 1,
       "geolocation_zip" : 1,
       "last_click" : 1,
       "opens" : 1,
   }
}
Type Parameter Description Example
Required for job list Name of the list to export Example
Optional for job hash_algo The algorithm to use for the hash of each user’s email address in the export file’s ‘hash’ column. The default algorithm is MD5. Set hash_algo to sha256 to use SHA256, instead. n/a
Optional for job fields The field(s) of data to export.
Note:

  • The exported URL contains PII hashed data. Using the fields parameter limits the CSV export to those specific fields (in addition to Profile ID and Email Hash).
  • Valid fields values:
    • clicks
    • domain
    • email_message
    • email_status
    • email_status_time
    • engagement
    • first_purchase_time
    • geolocation_city
    • geolocation_country
    • geolocation_state
    • geolocation_zip
    • largest_purchase_item_price
    • last_click
    • last_open
    • last_pageview
    • last_purchase_time
    • lifetime_message
    • lists
    • list_signup
    • opens
    • optout_time
    • pageviews
    • profile_created_date
    • purchase_count
    • purchase_incomplete
    • purchase_price
    • signup
    • top_device
    • vars
Example

 

import

Emails (Directly)

{
    "job":"import",
    "list":"List 1",
    "emails":"user1@sailthru.com,user2@sailthru.com,user3@sailthru.com"
}

File (Upload)

{
    "job":"import",
    "list":"List 1",
    "file":"/tmp/users.txt"
}

URL

{
    "job":"import",
    "list":"List 1",
    "url":"https://s3.amazonaws.com/sailthru-static/users.csv"
}

Response

{
    "job_id" : "58487498e9328b50588b4b54",
    "name" : "List Import: List 1",
    "list" : "List 1",
    "error" : false,
    "status" : "completed",
    "start_time" : "Wed, 07 Dec 2016 15:44:09 -0500",
    "end_time" : "Wed, 07 Dec 2016 15:44:10 -0500"
}
Type Parameter Description Example
Required for job list The name of the list to import to (if it does not exist, it will be created).

  • In addition to list, you must pass one of the following parameters, but not all three:
    • emails
    • file
    • url
Example
Required for job emails Emails to upload to the list Example
Required for job file File data to upload as a list. Note:

  • This is not a URL! File must be a CSV or text file with one email per line
  • The maximum upload file size is 1 GB
Example
Required for job url URL to pull data from Example
Optional for job signup_dates This parameter is for updating custom signup dates.

  • You must upload a CSV file with the first column titled “email,” and the second column titled “signup_date.”
  • Pass 1 or true to overwrite or set custom signup dates for existing users or new users
  • Date variables cannot be in UNIX.
  • How to set Custom Signup Dates
  • job Examples
Example

 

purchase_import

Example Call

{
    "job":"purchase_import",
    "file":"/tmp/file.txt"
}
Type Parameter Description Example
Required for job file UTF-8 text file containing JSON objects.

  • The file must contain one JSON object per line (separated by hard returns, not commas)
  • Each object must match the purchase API POST format, with the following exceptions:
    • date and extid are required
    • the following parameters should not be included, as they only apply to purchases recorded in realtime: message_id, incomplete, reminder_template, send_tempate, reminder_time
  • Max file size is 1 GB
Example

 

snapshot

Example Call

{
    "job":"snapshot",
    "query":
        {
            "source_list":"",
            "criteria":["domain"],
            "value":"sailthru.com"
        }   
}
Show response
{
    "job_id" : "584899e9e9328ba90a8b479b",
    "name" : "Snapshot: All users: email domain is s",
    "status" : "completed",
    "start_time" : "Wed, 07 Dec 2016 18:23:23 -0500",
    "end_time" : "Wed, 07 Dec 2016 18:23:44 -0500",
    "snapshot" : {
        "browsers" : [],
        "cities" : [],
        "countries" : [],
        "engagement" : [],
        "engagement_by_month" : [],
        "engagement_by_domain" : [],
        "horizon" : [],
        "hours" : {
            "00" : 0,
            "11" : 0,
            "22" : 0,
            "01" : 0,
            "12" : 0,
            "23" : 0,
            "02" : 0,
            "13" : 0,
            "03" : 0,
            "14" : 0,
            "04" : 0,
            "15" : 0,
            "05" : 0,
            "16" : 0,
            "06" : 0,
            "17" : 0,
            "07" : 0,
            "18" : 0,
            "08" : 0,
            "19" : 0,
            "09" : 0,
            "20" : 0,
            "10" : 0,
            "21" : 0
        },
        "interested" : [],
        "lists" : [],
        "purchase_counts" : [],
        "purchase_prices" : [],
        "site_hours" : {
            "00" : 0,
            "11" : 0,
            "22" : 0,
            "01" : 0,
            "12" : 0,
            "23" : 0,
            "02" : 0,
            "13" : 0,
            "03" : 0,
            "14" : 0,
            "04" : 0,
            "15" : 0,
            "05" : 0,
            "16" : 0,
            "06" : 0,
            "17" : 0,
            "07" : 0,
            "18" : 0,
            "08" : 0,
            "19" : 0,
            "09" : 0,
            "20" : 0,
            "10" : 0,
            "21" : 0
        },
        "top_purchase_items" : [],
        "total_count" : 0,
        "total_purchase_price" : 0,
        "total_purchasers" : 0
    }
}
snapshot
Type Parameter Description Example
Required for job query A query or search
Queries In The API
Example
Return for job query Data structure containing the query N/A
Return for job snapshot Data structure containing the results of the snapshot N/A

 

update

Type Parameter Description Example
Required for job url URL to pull data from

  • If you are using the url or file parameters, then you are pulling data from a url or file. There are two different formats you can use:
    • Simple – Email address per line. This lets you perform the same update on a list of users.
    • JSON – JSON object per line. This lets you specify individual updates on a per-user basis. Each line should contain a JSON object with the email element to identify the user, and any optional parameters: vars, lists, or optout.
Example call
Example JSON file
Required for job file File data to upload

  • The maximum upload file size is 1 GB
  • If you are using the url or file parameters, then you are pulling data from a url or file. There are two different formats you can use:
    • Simple – Email address per line. This lets you perform the same update on a list of users.
    • JSON – JSON object per line. This lets you specify individual updates on a per-user basis. Each line should contain a JSON object with the email element to identify the user, and any optional parameters: vars, lists, or optout.
Example JSON file
Required for job query A query or search
Queries In The API
Example
Optional for job update[vars] The key/value hash of vars to set Example
Optional for job update[lists] The key/value hash of lists to subscribe or unsubscribe to. 1 means subscribe, and 0 means unsubscribe. Example
Optional for job update[optout] Updates a user’s optout level

  • Valid optout values:
    • blast – Opts users out of campaigns only
    • all – Opts users out of all communications
    • basic – Opts the user out of all communications except templates marked as “basic”
    • none – Opts the user back in

FURTHER INFORMATION:
User Opt-Out Levels

Example
Optional for job update[delete_vars] An array of vars to delete from user profiles

  • This process is irreversible, so proceed with caution
Example
Optional for job signup_date Use JSON to update users or a user’s signup_date. Can also be passed along with these optional parameters: vars, lists or optout. Example

Parameter Examples

GET MODE
Type Parameter
Required job_id
Example
{
    "job_id":"4dd58f036803fa3b5500000b"
}

GET MODE
Type Parameter
Return N/A
Example
{
    "job_id":"4dd58f036803fa3b5500000b",
    "name":"List Import",
    "status":"completed",
    "start_time":"Fri, 20 May 2012 13:50:28 -0400",
    "end_time":"Fri, 20 May 2012 13:55:10 -0400",
    < The remaining info depends on the job type >
}

POST MODE
Type Parameter
Required job
Example
{
    "job":<string job type>
}

POST MODE
Type Parameter
Required For ad_inventory start_date
Example
{
    "job":"ad_inventory",
    "start_date":20120901,
    "end_date":20120925
}

POST MODE
Type Parameter
Required For ad_inventory end_date
Example

POST MODE
Type Parameter
Required For blast_query blast_id
Example
{
    "job":"blast_query",
    "blast_id":190940
}

POST MODE
Type Parameter
Return For blast_query filename
Example
{
    "filename":"my-list.csv"
}

POST MODE
Type Parameter
Return For blast_query export_url
Example
{
    "export_url":"https://s3.amazonaws.com/sailthru/path/to/export"
}

POST MODE
Type Parameter
Required For blast_save_list blast_id
Example
{
    "job":"blast_save_list",
    "blast_id":123456,
    "query":
        {
            "source_list":"Main",
            "criteria":["engagement_min"],
            "engagement":[5]
        },
     "list":"Opened-Jun-15-Campaign"
}

POST MODE
Type Parameter
Required For blast_save_list query
Example
{
    "job":"blast_save_list",
    "blast_id":123456,
    "query":
        {
            "source_list":"Main",
            "criteria":["engagement_min"],
            "engagement":[5]
        },
     "list":"Opened-Jun-15-Campaign"
}

POST MODE
Type Parameter
Required For blast_save_list list
Example
{
    "job":"blast_save_list",
    "blast_id":123456,
    "query":
        {
            "source_list":"Main",
            "criteria":["engagement_min"],
            "engagement":[5]
        },
     "list":"Opened-Jun-15-Campaign"
}

POST MODE
Type Parameter
Optional For blast_save_list report_email
Example
{
    "job":"blast_save_list",
    "query":
        {
            "source_list":"Main",
            "criteria":["engagement_min"],
            "engagement":[5]
        }     
    "list":"Opened-Jun-15-Campaign",
    "report_email":"example@sailthru.com"
}

POST MODE
Type Parameter
Required For blast_snapshot query
Example

POST MODE
Type Parameter
Required For blast_snapshot blast_id
Example
{
    "job":"blast_snapshot",
    "query":
        {
            "source_list":"Main",
            "criteria":["engagement_min"],
            "engagement":[5]
        },
    "blast_id":190940
}

POST MODE
Type Parameter
Required For content_update file
Example
Call
{
    "job":"content_update",
    "file":"/tmp/file.txt"
}
File content
 {"url":"https://example.com/1234/water_bottle" }
 {"url":"https://example.com/1234/water_bottle-outdoor", "inventory":47}
 {"url":"https://example.com/1234/water_bottle-sport", "title":"Sports Water Bottle","description":"A water bottle designed for athletes"}

POST MODE
Type Parameter
Required For delete_content type
Example
Delete all content:

{
 "job" : "delete_content",
 "type" : "all"
}

Delete all expired content:

{
 "job" : "delete_content",
 "type" : "expired"
}

POST MODE
Type Parameter
Required For delete_content type
Optional For delete_content start_date, end_date
Example
Delete all content published in the last 6 months of 2016 including on the specified dates:

{
 "job" : "delete_content",
 "type" : "all",
 "start_date" : "July 1, 2016",
 "end_date" : "Dec 31, 2016"
}

Delete only expired content published in the last 6 months of 2016 including the specified dates:

{
 "job" : "delete_content",
 "type" : "expired",
 "start_date" : "2016-07-01",
 "end_date" : "2016-12-31"
}

POST MODE
Type Parameter
Required For export_list_data list
Example
{
    "job":"export_list_data",
    "list":"MyUsers"
}

POST MODE
Type Parameter
Optional For export_list_data fields
Example
{
    "job":"export_list_data",
    "list":"MyUsers",
    "fields":
        {
            "opens":1,
            "vars":
                {
                    "userId":1,
                    "user_type":1
                }
        }
}


Example Call

{
    "job":"export_purchase_log",
    "start_date":20160101,
    "end_date":20160131
}

Example Response

{
    "job_id" : "58486fa1e661f07c198b45f6",
    "name" : "Export purchase logs from 20160101 to 20160131",
    "status" : "completed",
    "start_time" : "Wed, 07 Dec 2016 15:22:58 -0500",
    "end_time" : "Wed, 07 Dec 2016 15:23:04 -0500",
    "filename" : "purchase_log-20160101-20160131.csv",
    "export_url" : "https://s3.amazonaws.com/sailthru/export/2016/12/07/d699e4bd562eec65a1e0c2f47b111111"
}
POST MODE
Type Parameter
Required For export_purchase_log start_date, end_date
Example
{
    "job":"export_purchase_log",
    "start_date":20120131,
    "end_date":20120131
}

POST MODE
Type Parameter
Required For import list
Example
{
    "job":"import",
    "list":"My List"
}

POST MODE
Type Parameter
Required For import emails
Example
{
    "job":"import",
    "list":"My List",
    "emails":
        "example1@sailthru.com,example2@sailthru.com,example3@sailthru.com"
}

POST MODE
Type Parameter
Required For import file
Example
{
    "job":"import",
    "list":"My List",
    "file":".../Users/myusername/Documents/myfile.csv"
}

POST MODE
Type Parameter
Required For import url
Example
{
    "job":"import",
    "list":"My List",
    "url":"https://www.example.com/feed/ourfeed"
}

POST MODE
Type Parameter
Optional For import signup_dates
Example
{
    "job":"import",
    "list":"My List",
    "url":"https://www.example.com/feed/ourfeed"
    "signup_dates":1
}

POST MODE
Type Parameter
Required For snapshot query
Example
{
    "job":"snapshot",
    "query":
        {
            "source_list":"Main",
            "criteria":["engagement_min"],
            "engagement":[5]
        }   
}

POST MODE
Type Parameter
Required For update url
Example
{
    "job":"update",
    "url":"https://example.com"
}
See also: Bulk update JSON file example.

POST MODE
Type Parameter
Optional For update N/A
Example
Example content of JSON file for bulk update, sent with an update call or referenced by URL:

{"id":"user1@example.com", "keys":{"extid":12}, "fields":{"keys":1}, "vars":{"updated":"yes"}, "lists":{"Update List":1}}
{"id":"user2@example.com", "keys":{"extid":13}, "fields":{"keys":1}, "lists":{"Update List":0}}
{"id":"user3@example.com", "keys":{"extid":14}, "fields":{"keys":1}, "optout":"all"}
{"id":"user4@example.com", "signup_date":"1987-08-01"}

Object 1: Adding a key, adding a var, adding to a list
Object 2: Adding a key, removing from a list
Object 3: Adding a key, setting status to optout all
Object 4: Setting custom signup date

Click here to view the same content in an easier-viewed but unsupported format.
{
   "id":"user1@example.com",
   "keys":{"extid":12},
   "fields":{"keys":1},
   "vars":{"updated":"yes"},
   "lists":{"Update List":1}
}
{
   "id":"user2@example.com",
   "keys":{"extid":13},
   "fields":{"keys":1},
   "lists":{"Update List":0}
}
{
   "id":"user3@example.com",
   "keys":{"extid":14},
   "fields":{"keys":1},
   "optout":"all"
}
{
   "id":"user4@example.com",
   "signup_date":"1987-08-01"
}

POST MODE
Type Parameter
Required For update query
Example
{
    "job":"update",
    "query":
        {
            "source_list":"Main",
            "criteria":["engagement_min"],
            "engagement":[5]
        }
}

POST MODE
Type Parameter
Optional For update update[vars]
Example
{
    "job":"update",
    "query":{"source_list":"Main"},
    "update":
    {
        "vars":
        {
            "name":"Joe One",
            "company":"Example Company"
        }
    }
}

POST MODE
Type Parameter
Optional For update update[lists]
Example
{
    "job":"update",
    "query":{"source_list":"Main"},
    "update":
        {
            "lists":
                {
                    "Main-copy":1
                }
        },
}
or
{
    "job":"update",
    "query":{"source_list":"Main"},
    "update":
        {
            "email":"example1@example.com",
            "lists":
                {
                    "Main-copy":1
                }
        },
        {
            "email":"example2@example.com",
            "lists":
                {
                    "Main-copy":0
                }
        }
}

POST MODE
Type Parameter
Optional For update update[optout]
Example
{
    "job":"update",
    "query":{"source_list":"mylistname"},
    "update":{"optout":"all"}
}

POST MODE
Type Parameter
Optional For update update[delete_vars]
Example
{
    "job":"update",
    "query":
        {
            "source_list":"Main"
        },
    "update":
        {
            "delete_vars":
                [
                    "name",
                    "company"
                ]

        }
}

POST MODE
Type Parameter
Optional For update signup_date
Example
{"email":"someone@somedomain.com", "signup_date":"Jan 18, 2013"}

POST MODE
Type Parameter
Required For purchase_import file
Example
Call JSON
{
    "job":"purchase_import",
    "file":"/tmp/file.txt"
}
File Content (Supported format: one object per line)
{"email":"user1@example.com","date":"2016-06-01","purchase_keys":{"extid":"purchase101"},"items":[{"qty":1,"id":"2005","title":"T-Shirts in Black","url":"http://example.com/products/tshirts-black","price":4000,"tags":["shirts","under100","color-black"],"vars":{"sailthru_category":"clothing"},"image":"http://email-media.s3.amazonaws.com/Sailthru/default/images/stock/t-shirts.jpg"},{"qty":1,"id":"SKU1002","title":"Women's Shoes in Black and White","url":"http://example.com/products/womens-shoes-in-black","price":25000,"tags":["shoes","footwear","formalwear","womens","color-black"],"vars":{"sailthru_category":"shoes"},"image":"http://email-media.s3.amazonaws.com/Sailthru/default/images/stock/high_heels.jpg"},{"qty":2,"id":"SKU1001","title":"Men's Shoes in Black","url":"http://example.com/products/mens-shoes-in-black","price":10000,"tags":["shoes","footwear","formalwear","mens","color-black"],"vars":{"sailthru_category":"shoes"},"image":"http://email-media.s3.amazonaws.com/Sailthru/default/images/stock/black_mens_shoes.jpg"}],"vars":{"order_level_var":"abcd1234"},"adjustments":[{"price":-5000,"title":"Sale"},{"price":-2000,"title":"coupon"}]}
{"email":"user2@example.com","date":"2016-06-02","purchase_keys":{"extid":"purchase202"},"items":[{"qty":2,"id":"2005","title":"T-Shirts in Black","url":"http://example.com/products/tshirts-black","price":4999,"tags":["shirts","under100","color-black"],"vars":{"sailthru_category":"clothing","item_level_var":"promotional_item"},"image":"http://email-media.s3.amazonaws.com/Sailthru/default/images/stock/t-shirts.jpg"}],"vars":{"order_level_var":"efhg6789"},"tenders":[{"price":"9998","title":"Discover"}]}
{"email":"user3@example.com","date":"2016-06-03","purchase_keys":{"extid":"purchase303"},"items":[{"qty":1,"id":"SKU1002","title":"Women's Shoes in Black and White","url":"http://example.com/products/womens-shoes-in-black","price":24900,"tags":["shoes","footwear","formalwear","womens","color-black"],"vars":{"sailthru_category":"shoes"},"image":"http://email-media.s3.amazonaws.com/Sailthru/default/images/stock/high_heels.jpg"},{"qty":1,"title":"Men's Shoes in Black","id":"SKU1001","url":"http://example.com/products/mens-shoes-in-black","price":19999,"tags":["shoes","footwear","formalwear","mens","color-black"],"vars":{"sailthru_category":"shoes"},"image":"http://email-media.s3.amazonaws.com/Sailthru/default/images/stock/black_mens_shoes.jpg"}],"vars":{"order_level_var":"shoes_purchase"},"adjustments":[{"price":2500,"title":"Express Shipping"}]}
Click here to view the same content in an easier-viewed but unsupported format.
{
  "email": "user1@example.com",
  "date": "2016-06-01",
  "purchase_keys": {
    "extid": "purchase101"
  },
  "items": [{
    "qty": 1,
    "id":"2005",
    "title": "T-Shirts in Black",
    "url": "http://example.com/products/tshirts-black",
    "price": 4000,
    "tags": ["shirts", "under100", "color-black"],
    "vars": {
      "sailthru_category": "clothing"
    },
    "image": "http://example.com/images/stock/t-shirts.jpg"
  }, {
    "qty": 1,
    "id":"SKU1002",
    "title": "Women's Shoes in Black and White",
    "url": "http://example.com/products/womens-shoes-in-black",
    "price": 25000,
    "tags": ["shoes", "footwear", "formalwear", "womens", "color-black"],
    "vars": {
      "sailthru_category": "shoes"
    },
    "image": "http://example.com/images/stock/high_heels.jpg"
  }, {
    "qty": 2,
    "id":"SKU1001",
    "title": "Men's Shoes in Black",
    "url": "http://example.com/products/mens-shoes-in-black",
    "price": 10000,
    "tags": ["shoes", "footwear", "formalwear", "mens", "color-black"],
    "vars": {
      "sailthru_category": "shoes"
    },
    "image": "http://example.com/images/stock/black_mens_shoes.jpg"
  }],
  "vars": {
    "order_level_var": "abcd1234"
  },
  "adjustments": [{
    "price": -5000,
    "title": "Sale"
  }, {
    "price": -2000,
    "title": "coupon"
  }]
}

{
  "email": "user2@example.com",
  "date": "2016-06-02",
  "purchase_keys": {
    "extid": "purchase202"
  },
  "items": [{
    "qty": 2,
    "id":"2005",
    "title": "T-Shirts in Black",
    "url": "http://example.com/products/tshirts-black",
    "price": 4999,
    "tags": ["shirts", "under100", "color-black"],
    "vars": {
      "sailthru_category": "clothing",
      "item_level_var": "promotional_item"
    },
    "image": "http://example.com/images/stock/t-shirts.jpg"
  }],
  "vars": {
    "order_level_var": "efhg6789"
  },
  "tenders": [{
    "price": "9998",
    "title": "Discover"
  }]
}

{
  "email": "user3@example.com",
  "date": "2016-06-03",
  "purchase_keys": {
    "extid": "purchase303"
  },
  "items": [{
    "qty": 1,
    "id":"SKU1002",
    "title": "Women's Shoes in Black and White",
    "url": "http://example.com/products/womens-shoes-in-black",
    "price": 24900,
    "tags": ["shoes", "footwear", "formalwear", "womens", "color-black"],
    "vars": {
      "sailthru_category": "shoes"
    },
    "image": "http://example.com/images/stock/high_heels.jpg"
  }, {
    "qty": 1,
    "title": "Men's Shoes in Black",
    "id":"SKU1001",
    "url": "http://example.com/products/mens-shoes-in-black",
    "price": 19999,
    "tags": ["shoes", "footwear", "formalwear", "mens", "color-black"],
    "vars": {
      "sailthru_category": "shoes"
    },
    "image": "http://example.com/stock/black_mens_shoes.jpg"
  }],
  "vars": {
    "order_level_var": "shoes_purchase"
  },
  "adjustments": [{
    "price": 2500,
    "title": "Express Shipping"
  }]
}

 


POST MODE
Type Parameter
Optional report_email
Example
{
    "job":<string job type>,
    "report_email":"example@sailthru.com"
}

POST MODE
Type Parameter
Optional postback_url
Example
{
    "job":<string job type>,
    "postback_url":"https://www.example.com/service/job-result"
}

Additional Examples and Use Cases

Add Users to a New List
{"job":"update","report_email":"myemail@mydomain.com","query":{"source_list":"Main"},"update":{"lists":{"Main-copy":1}}}

This adds all the users on the list “Main” to a new list called “Main-copy.”

Add Users to a List using a URL File (in PHP)
$report_email = "reportemail@domain.com";
$url = "https://www.urlhere.com";
$client->processUpdateJobFromUrl($url, array("lists"=>array("listnamegoeshere"=>1)), $report_email ,  false)
Bulk Update the Optout Status of a List of Users
{'job':'update','query':{'source_list':'mylistname'},'update':{'optout':'all'}}
Query Users and Add That Segment to a New List
{"job":"update","report_email":"myemail@mydomain.com","query":{"source_list":"Main","criteria:["engagement_min"],"engagement":[5]},"update":{"lists":{"Main-copy":1}}}

This query checks for users on the list “Main” that have an engagement level of at least 5, and then adds those users to a new list called “Main-copy.”

Query Users on Multiple Lists and Add That Segment to a New List
{"job":"update","report_email":"myemail@mydomain.com","query":{"source_list":".multiple","multiple_source_list":["Main","Another List"],"criteria:["engagement_min"],"engagement":[5]},"update":{"lists":{"My Copy":1}}}

This query checks for users on the lists “Main” and “Another List” that have an engagement level of at least 5, and then adds those users to a new list called “My Copy.”

Query a Campaign and Add Those Users to a List

Example in PHP:

$sailthru->apiPost('job', array(
  'job' => 'blast_save_list',
  'blast_id' => '123456',
  'query' => array('criteria' => array('match'), 'field' => array('gender'), 'value' => array('male')),
  'list' => 'male list'
));

Example in JSON:

{"job":"blast_save_list","blast_id":"1234567","list":"My List","query":{"criteria":["valid"]}}
Set Custom Signup Date on a New/Existing Group of Users

Upload a CSV of new or existing users using the “import” parameter of the Job call, and set a custom signup date on these users. Note that the CSV must have two columns: emailand signup_date. Additionally, the “signup_dates” parameter must be passed in the call with a value of 1or true.

Example in PHP:

$api_client = new Sailthru_Client($client_api_key, $client_secret, $api_url);
$api_client.apiPost("job", array("job" => "import", "list" => "test_list", "signup_dates" => "true", "file" => "hello.csv"), array('file'));

Example in Ruby:

sc = Sailthru::SailthruClient.new("123456789101112131415","123456789101112131415","https://api.sailthru.com")
sc.api_post(:job, {"job"=>"import","list"=>"test2","signup_dates"=>true,"file"=>"hello.csv"}, "file")
Set Vars on a Group of Users

Find all users on the list Main who have an email address at sailthru.com and who open email more than 50% of the time in the state of NY. Add a var to those users called “is_sailthru” and set the value as true.

Example in JSON:

{"job":"update","report_email":"me@mydomain.com",
"query":{
   "source_list":"Main",
   "criteria":["domain","geo_state"],
   "value":["sailthru.com","NY US"],
   "geo_frequency":[null,50]
   },
"update":{"vars":{"is_sailthru":1}
   }
}
Third-Party Opt-out

You are working with a third party that is able to get you occasional exports of email addresses that need to be opted out on Sailthru.

Take the list of third party email addresses and turn them into a new line-separated list of emails, then put them on a private URL and:

$sailthru->apiPost('job', array(
  'job' => 'update',
  'url' => 'https://path/to/emails',
  'update' => array('optout' => 'blast'),
));

Or POST directly as a file:

$sailthru->apiPost('job', array(
  'job' => 'update',
  'update' => array('optout' => 'blast'),
), array(
  'file' => '/path/to/emails',
));

 

Populating Campaign With Per-User Data

You want to send a campaign which has a section showing how many new friends have joined the site per-user. You want to send the campaign as soon as possible after the data transfer is complete.

Create a JSON-format file with the users, setting a variable for each one, like so:

{"email":"foo@example.com","vars":{"new_friends":["Ian","Will","Praj","Eli","Emily"]}}
{"email":"bar@example.com","vars":{"new_friends":["Neil","John"]}}
Regular List Cleaning

You want to automatically remove disengaged users from your main  list and move them onto a disengaged  list. (You could achieve a similar effect by just using Smart Lists, but let’s assume for some reason you need to use normal lists.)

$sailthru->apiPost('job', array(
  'job' => 'update',
  'query' => array('source_list' => 'main',
                   'criteria' => array('engagement_max'),
                   'engagement' => array(2)),
  'update' => array('lists' => array('main' => 0, 'disengaged' => 1)),
));
Multiple Source Lists

You can query multiple lists at the same time. Use multiple source lists within the JOB call, ‘update’ type. For example:

("job",{"job"=>"update","report_email"=>"joe@example.com","query"=>{"source_list"=>".multiple", "multiple_source_list" => ["listname1","listname2"]}, "update"=>{"name of merged list" => 1}})

Error Codes 

Job HTTP Code Error Code Error Message Notes
blast_query 400 2 Missing required parameter: blast_id
blast_query 404 13 Unknown blast_id
blast_query 403 99 You may not export a blast that has been sent
blast_query 400 99 Blasts stats are not available yet for {BLAST_ID} so this job cannot begin.  Please try again shortly
blast_save_list 400 2 Missing required parameter: blast_id/query/list
blast_save_list 200 99 Invalid list name:
blast_save_list 400 13 Invalid blast_id
blast_save_list 400 99 Blasts stats are not available yet for {BLAST_ID} so this job cannot begin.  Please try again shortly
blast_snapshot 400 13 Invalid blast_id
blast_snapshot 400 99 Blasts stats are not available yet for {BLAST_ID} so this job cannot begin.  Please try again shortly
export_list_data 400 2 Missing required parameter: list
export_list_data 404 99 List not found
export_purchase_log 400 18 Missing required parameter: start_date,end_date
export_purchase_log 400 18 Invalid start_date/end_date fromat
export_purchase_log 400 18 Invalid date range. Start Date canot be later than End Date
export_purchase_log 400 18 Invalid date range. Up to 31 days allowed but {day_range} given Start_date and end_date too far apart
import 400 2 Missing required parameter: list
import 200 99 Invalid list name:
import 400 99 One of the following parameters is required: emails, url, or file
import 400 99 Invalid URL
list_erase 200 99 The lists parameter must be passed as an array
list_erase 200 99 Request exceeds limit of 1,000 lists. No lists deleted
File Import jobs(content_update,purchase_import, import) 400 99 File Parameter is required
File Import jobs(content_update,purchase_import,import) 400 99 The size of the file exceeds the maximum upload file size Max upload is 1gb
File Import jobs(content_update,purchase_import,import) 400 99 Failed to upload file
File Import jobs(content_update,purchase_import,import) 400 99 Unable to determine the size of the file Might not be reachable error
File Import jobs(content_update,purchase_import,import) 400 99 File not set Might not be reachable error
snapshot 400 2 Missing required parameter: query,update
update 400 99 One of the following parameters is required: emails, url, file, or query
update 400 99 List name: {LIST_NAME} failed validation
update 400 99 List name cannot contain a $ character
update 400 99 Invalid URL:
update When using a file, same errors applies as import job
Top