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.

    Copy 
    {
        "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:

    Copy 
    {
       "_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

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

    Example Response

    Copy 
    {
        "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

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

    Example Response

    Copy 
    {
        "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

    Copy 
    {
        "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

    Copy 
    {
        "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 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

    Copy 
    {
        "job":"blast_snapshot",
        "query":
            {
                "source_list":"Main",
                "criteria":["engagement_min"],
                "engagement":[5]
            },
        "blast_id":"190940"
    }

    Show Example Response

    Copy 
    {
        "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

    Copy 
    {
        "job":"snapshot",
        "query":
            {
                "source_list":"",
                "criteria":["domain"],
                "value":"sailthru.com"        
                    }   
    }

    Response

    Copy 
    {
        "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:

    Copy 
    $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:

    Copy 
    {"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
    400 99 Invalid JSON provided