job – Queries

Query users to see who received a specific campaign or to generate a snapshot of their analytics.

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.

Endpoint URL: https://api.sailthru.com/<span style="color: #333399;">job

Query Jobs

  • 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.
  • snapshot – Query your users and generate a detailed snapshot of their analytics (similar to the Snapshot Report in the Sailthru interface).

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 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 it can be optionally 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 subsequent 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

blast_query

The following section contains job-specific parameters and examples for 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 2 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 two-factor (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_query Examples

Required – blast_id
POST MODE
Type Parameter
Required For blast_query blast_id
Example
{
    "job":"blast_query",
    "blast_id":190940
}
Return filename
POST MODE
Type Parameter
Return For blast_query filename
Example
{
    "filename":"my-list.csv"
}
Return export_url
POST MODE
Type Parameter
Return For blast_query export_url
Example
{
    "export_url":"https://s3.amazonaws.com/sailthru/path/to/export"
}

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

This example represents a job that has reached completed status. See How It Works, above, for more information.

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

This example represents a job that has reached completed status. See How It Works, above, for more information.

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_save_list Examples

Required – blast_id
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"
}

Required – query
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"
}

Required – list
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"
}

Optional – report_email
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"
}

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" : []
}

This example represents a job that has reached completed status. See How It Works, above, for more information.

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

blast_snapshot Examples

Required – blast_id
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
}

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

This example represents a job that has reached completed status. See How It Works, above, for more information.

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

snapshot Examples

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

Use Cases

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

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
snapshot 400 2 Missing required parameter: query,update
snapshot 400 2 Missing required parameter: query,update
Top