job API

Start or get the status of a background job, such as a data import or export. 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 GET call requests the status of the posted job.

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

  • report_email – An email that receives job-completion results
  • 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_keyand sig, so that the request can be optionally verified as a legitimate Sailthru request
API Base URL
job https://api.sailthru.com/job
Description

GET MODE
Type Parameter Description Example
Required job_id A job’s unique identification Example
Return status A job’s status: completed, pending, or error Example
Return name A job’s name
Return start_time A job’s start date and time; this field may not be available if job has not started
Return end_time A job’s end date and time; this field will not be available if job is not completed

POST MODE
Type Parameter Description Example
Required job Job typeFURTHER INFORMATION:
job Parameters
Example
Optional report_email Email that receives a short report upon job completion Example
Optional 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 Example

job
Type Parameter Description Example
Job Type For job ad_inventory Review your available adFlight advanced inventory over a date range.FURTHER INFORMATION:
ad_inventory Parameters
N/A
Job Type For job blast_query Export campaign data in .csv format.FURTHER INFORMATION:
blast_query Parameters
N/A
Job Type For job blast_save_list Query your users that received a specific campaign, and save that new segment to a new or existing list.FURTHER INFORMATION:
blast_save_list Parameters
N/A
Job Type For job 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).FURTHER INFORMATION:
blast_snapshot Parameters
N/A
Job Type For job export_list_data Export user data from a list in .csv format.FURTHER INFORMATION:
export_list_data Parameters
N/A
Job Type For job export_purchase_log Export user data from a list in .csv format.FURTHER INFORMATION:
export_purchase_log Parameters
N/A
Job Type For job export_scheduled_sends Download a .csv report of all currently-scheduled transactional sends. No additional parameters are required N/A
Job Type For job import Import a number of email addresses into a list.FURTHER INFORMATION:
import Parameters
N/A
Job Type For job 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
Job Type For job snapshot Query your users and generate a detailed snapshot of their analytics (similar to the Snapshot Report in the Sailthru interface).FURTHER INFORMATION:
snapshot Parameters
N/A
Job Type For job 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.TIP:

  • 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

FURTHER INFORMATION:
update Parameters

N/A
Job Type For job purchase_import Updates historical purchase dataFURTHER INFORMATION:
purchase_import Parameters
N/A

ad_inventory
Type Parameter Description Example
Required For ad_inventory start_date Start of the date range to examineTIP:

  • Date range between start_date and end_date cannot exceed 90 days
Example
Required For ad_inventory end_date End of the date range to examine Example
Return For ad_inventory inventory Data structure containing available and used inventory by day N/A
Return For ad_inventory conflicts Data structure containing days that represent conflicts under current scheduling N/A

blast_query
Type Parameter Description Example
Required For blast_query blast_id A valid blast identification Example
Return For blast_query filename The generated file name Example
Required For blast_query export_url A URL pointing to the exported data. The link expires after 24 hours.TIP:

  • 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

blast_save_list
Type Parameter Description Example
Required For blast_save_list blast_id Identification of the blast you wish to take a snapshot of Example
Required For blast_save_list query A query or searchFURTHER INFORMATION:
Queries In The API
Example
Required For blast_save_list list The name of the list to add users to (if it does not exist, it will be created)TIP:

  • Querying a list is not required, since you are already querying the blast itself
Example
Optional For blast_save_list report_email Receive an email notification when a job is completeFURTHER INFORMATION:
job Examples
Example

blast_snapshot
Type Parameter Description Example
Required For blast_snapshot query A query or searchFURTHER INFORMATION:
Queries In The API
Example
Required For blast_snapshot blast_id A valid blast identification Example
Return For blast_snapshot stats Data structure containing the results of the snapshot N/A

export_list_data
Type Parameter Description Example
Required For export_list_data list Name of the list to export Example
Optional For export_list_data fields The field(s) of data to exportTIP:

  • 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

export_purchase_log
Type Parameter Description Example
Required For export_purchase_log start_date Purchase report’s start dateTIP:

  • 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 export_purchase_log end_date Purchase report’s end date Example

import
Type Parameter Description Example
Required For import list The name of the list to import to (if it does not exist, it will be created).TIP:

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

  • This is not a URL! File must be a .csv or text file with one email per line
  • The maximum upload file size is 100 MB
Example
Required For import url URL to pull data from Example
Optional For import signup_dates This parameter is for updating custom signup dates.TIP:

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

FURTHER INFORMATION:
Set Custom Signup Dates
job Examples

Example

snapshot
Type Parameter Description Example
Required For snapshot query A query or searchFURTHER INFORMATION:
Queries In The API
Example
Return For snapshot query Data structure containing the query N/A
Return For snapshot snapshot Data structure containing the results of the snapshot N/A

update
Type Parameter Description Example
Required For update emails Emails to update Example
Required For update url URL to pull data fromTIP:

  • 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
Required For update file File data to uploadTIP:

  • The maximum upload file size is 100 MB
  • 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.
N/A
Required For update query A query or searchFURTHER INFORMATION:
Queries In The API
Example
Optional For update update[vars] The key/value hash of vars to set Example
Optional For update update[lists] The key/value hash of lists to subscribe or unsubscribe to. 1 means subscribe, and 0 means unsubscribe. Example
Optional For update update[optout] Updates a user’s optout levelTIP:

  • 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 update update[delete_vars] An array of vars to delete from user profilesTIP:

  • This process is irreversible, so proceed with caution
Example
Optional For update 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

purchase_import
Type Parameter Description Example
Required For purchase_import file Imported fileTIP:

  • File content should be in JSON, and each line should represent the same formatting as an individual purchase API POST
  • Each individual purchase in the file must contain an extid
  • Max files size is 100 MB
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
{
    "job":"blast_shapshot",
    "query":
        {
            "source_list":"Main",
            "criteria":["engagement_min"],
            "engagement":[5]
        },
    "blast_id":190940
}

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

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

POST MODE
Type Parameter
Required For export_purchase_log start_date
Example
{
    "job":"export_purchase_log",
    "start_date":20120131,
    "end_date":20120131
}

POST MODE
Type Parameter
Required For export_purchase_log end_date
Example

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 emails
Example
{
    "job":"update",
    "emails":
        {
            "example1@sailthru.com",
            "example2@sailthru.com",
            "example3@sailthru.com"
        }
}

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

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
{
    "job":"purchase_import",
    "file":"/tmp/file.txt"
}

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