job

Overview

Start or get the status of a background job, such as a data import or export. Jobs are asynchronous – they may take minutes or hours to run, depending on how large they are. Therefore, the job POST call will return a job_id, which you can use later to request the current status of the job with the GET call.

In addition, there are two other mechanisms you can use to notify you when a job is complete. These are optional parameters for any job call: report_email- an email to receive a short report when the job is finished. postback_url- a URL that will receive a POST with the results of the job (the same data that you would get from a GET call on the job, with two additional parameters: api_keyand sig, so that the request can be optionally verified as a legitimate Sailthru request)

Base URL

https://api.sailthru.com/job

GET Mode

Fetch status of a job

Required
Parameter Description Example
job_id Job ID 4dd58f036803fa3b5500000b
Return Value

Will return a data structure including some or all of the following information:

Field Description Example
job_id Unique Job ID 4dd58f036803fa3b5500000b
status completed, pending or error pending
name name of the job List Import
start_time date time when the job was started; this field may not be available if job is not yet started Fri, 20 May 2012 13:50:28 -0400
end_time date time when the job finished; this field will not be available if job is not completed Fri, 20 May 2012 13:55:10 -0400

For export jobs including export_list_data and blast_query, export_url will be returned if the job is completed and it's not expired. If the job is expired, expired field with value true will be returned.

Currently, all export URL of export jobs are removed after approximately 2 hours of creation.

Additional information returned will depend on the type of the job, and is documented below under "Job Types".

 

POST Mode

Request that a job start processing.

Required Parameters
Parameter Description Example
job Type of the job import
Optional Parameters
Parameter Description Example
report_email Email to receive a short report when the job is complete example@example.com
postback_url URL to post the results of the job when the job is complete http://www.example.com/service/job-result

Other required and optional parameters depend on the job type, as follows:

Examples

Job Types

ad_inventory

Review your available adFlight Advanced inventory over a date range.

Required Parameters
Parameter Description Example
start_date Start of the date range to examine 20120901
end_date End of the date range to examine 20121231
Return Value
inventory Data structure containing available and used inventory by day  
conflicts Data structure containing days that represent conflicts under current scheduling  

blast_query

Export campaign data in CSV format

Additional Required Parameters
Parameter Description Example
blast_id Valid Blast Id 190940
Return Value
blast_id Blast ID 190940
filename The filename generated my-list.csv
export_url A URL pointing to the exported data. The data will be removed after 24 hours. http://s3.amazonaws.com/sailthru/path/to/export

The export URL will contain PII hashed data.

blast_save_list

Query your userbase who received a specific campaign and save that new segment to a new or existing list. 

Parameter Description Example
blast_id ID of the blast you wish to take a snapshot of 123456
query Query – see query for the exact format query[criteria][0]=domain
list name of the list to add users to (if it doesn't exist, it will be created) Opened-Jun-15-Campaign
Optional Parameters
Parameter Description Example
report_email Receive an email notification when this job has completed. "report_email":"me@mydomain.com"

Please see examples here

blast_snapshot

Query your userbase who received a specific campaign and generate a detailed snapshot of their analytics (similar to the Snapshot Report in the Sailthru interface).

Required Parameters
Parameter Description Example
query Query – see query for the exact format query[criteria][0]=domain
blast_id id of the blast you wish to take a snapshot of  
Return Value
stats Data structure containing the results of the snapshot  

export_list_data

Export user data from a list in CSV format

Additional Required Parameters
Parameter Description Example
list Name of the list to export my list
Optional Parameters
Parameter Description Example
fields The field or fields of data to export. {"job":"export_list_data","list":"MyUsers",
"fields":{"vars":{"userId":1,"user_type":1}}}
The export URL will contain PII hashed data.

 

The valid values for 'fields' above are:

'domain' ,'engagement' ,'lists' ,'profile_created_date' ,'signup' ,'opens' ,'clicks' ,'pageviews' ,'last_open' ,'last_click' ,'last_pageview' ,'optout_time' ,'delivery_status_time' ,'delivery_message' ,'top_interest_tags' ,'list_signup' ,'geolocation_city' ,'geolocation_state' ,'geolocation_country' ,'geolocation_zip' ,'lifetime_message' ,'first_purchase_time' ,'purchase_count' ,'purchase_price' ,'purchase_incomplete' ,'last_purchase_time' ,'largest_purchase_item_price' ,'top_device'

export_scheduled_sends

Download a CSV report of all currently scheduled transactional sends. No additional parameters are required.

import

Import a number of email addresses into a list

Required Parameters
Parameter Description Example
list Name of a list to make import; if list doesn't exist, it will be created my list
Additional Required Parameters

You must pass one of the below, but not both:

Parameter Description Example
emails Comma separated emails john@example.com,joe@example.com
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. /Users/myusername/Documents/myfile.csv
url URL to pull data from – see "Data File Format" below http://www.example.com/feed/ourfeed

Max upload file size for file parameter is 100 MB. 

 

Optional Parameters
Parameter Description Example
signup_dates Pass 1or true to overwrite/set custom signup dates for existing users or new users. You must also upload a CSV file (the first column must be headed email, and the second column headed signup_date). Please see an example here for details. 1

snapshot

Query your userbase and generate a detailed snapshot of their analytics similar to that shown in the Snapshot Report in the Sailthru interface.

Required Parameters
Parameter Description Example
query Query – see query for the exact format {"job":"snapshot","report_email":"myname@mydomain.com","query":{"source_list":"Main","query_mode":"and","criteria":["domain"],"value":["gmail.com"]}}
Return Value On Completion
query Data structure containing the query  
snapshot Data structure containing the results of the snapshot  

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.

Required Parameters

You must pass one of the below, but not more than one. The below determines the users to operate on.

Parameter Description Example
emails Comma separated list of emails to perform the update on john@example.com,ian@sailthru.com
url URL to pull data from – see "Data File Format" below http://www.example.com/feed/ourfeed
file File data to upload – see file format below  
query Query – see queries for format  
Optional Parameter: update

If you want to apply the same update to all of the users specified, you should pass the update parameter. The possible values of the update parameter are similar to that of the POST parameters of the email API call.

Parameter Description
update[vars] key/value hash of vars to set
update[lists] key/value hash of lists to subscribe or unsubscribe to, where 1means subscribe and 0means unsubscribe
update[optout] blastto opt users out of campaigns only, allto opt users out of all communications, basicto opt the user out of all communications except templates marked as 'basic', noneto opt the user back in. Please see optout levels here
Data File Format

If you are using the url or file format, then you are pulling from a file or URL. This can be one of two formats:

  • Simple format: email address per line. In this case you are just specifying a list of users to perform the same updates on (as specified by the update parameter)
  • JSON format: JSON object per line. This lets you specify individual updates on a per-user basis. Each line should contain a JSON object containing an email element to identify the user, and optionally vars, lists, or optout as described above.
{"email":"ian@sailthru.com","vars":{"name":"Ian White","company":"Sailthru"},"lists":{"Sailthru Employees":1}}
{"email":"praj@sailthru.com","vars":{"name":"Prajwal Tuladhar","company":"Sailthru"},"lists":{"Sailthru Employees":1}}
{"email":"john@example.com","vars":{"name":"John Doe","company":"Anycorp"},"lists":{"Sailthru Customers":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}})

 

Examples

See Job Update Examples for sample calls.