job – Content

Create, update, or remove content or lists.

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

Content jobs

• content_update - Create or Update content from a JSON file.
• delete_content - Remove content from your Content Library in bulk. This is helpful if there are pages within your content that were unintentionally or incorrectly spidered. You can delete all content or only expired content. In both cases you can narrow the selection to only delete content published during a specified date range.
• list_erase - Delete one or more lists by name.

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

Response Parameters

POST Mode

Required Parameters

Optional Parameters

content_update

Create or Update content from a JSON file.

Example Call

{
    "job":"content_update",
    "file":"/tmp/file.txt"
}

Example Response

{
    "job_id" : "5848632be9328bab2a8b482b",
    "name" : "Content Update",
    "status" : "completed",
    "start_time" : "Wed, 07 Dec 2016 14:29:52 -0500",
    "end_time" : "Wed, 07 Dec 2016 14:29:52 -0500",
    "invalid_count" : 0,
    "successful_count" : 3
}

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

content_update Examples

content_update POST

{
    "job":"content_update",
    "file":"/tmp/file.txt"}

{"url":"https://example.com/1234/water_bottle" }
{"url":"https://example.com/1234/water_bottle-outdoor", "inventory":47}
{"url":"https://example.com/1234/water_bottle-sport", "title":"Sports Water Bottle",
"description":"A water bottle designed for athletes"}

delete_content

Remove content from your Content Library in bulk.

Delete All

{
 "job" : "delete_content",
 "type" : "all"
}

Delete All Expired

Delete all expired content:

{
 "job" : "delete_content",
 "type" : "expired"
}

Delete All in Range

Delete all content published in the last 6 months of 2016 including on the specified dates:

{
 "job" : "delete_content",
 "type" : "all",
 "start_date" : "2016-07-01",
 "end_date" : "2016-12-31"
}

Delete Expired in Range

Delete only expired content published in the last 6 months of 2016 including the specified dates:

{
 "job" : "delete_content",
 "type" : "expired",
 "start_date" : "2016-07-01",
 "end_date" : "2016-12-31"
}

delete_content Examples

delete_content Example

{
 "job" : "delete_content",
 "type" : "all"
}

{
 "job" : "delete_content",
 "type" : "expired"
}

delete_content Example 2

{
 "job" : "delete_content",
 "type" : "all",
 "start_date" : "July 1, 2016",
 "end_date" : "Dec 31, 2016"
}

{
 "job" : "delete_content",
 "type" : "expired",
 "start_date" : "2016-07-01",
 "end_date" : "2016-12-31"
}

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.

Error Codes