job – Queries - Sailthru Documentation

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/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 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 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 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
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
	400	99	Invalid JSON provided