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.

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

content_update

Create or Update content from a JSON file.

Example Call

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

Example Response

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

Type Parameter Description Example
Required for job file Text file with one JSON object per line, each representing a valid Content API call. Each line requires a URL. All optional parameters are supported, including inventory. Example

content_update Examples

content_update POST
POST MODE
Type Parameter
Required For content_update file
Example
Call
{
    "job":"content_update",
    "file":"/tmp/file.txt"}
File content
{"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

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

Delete All Expired

Delete all expired content:

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

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

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

 

Type Parameter Description Example
Required for job type all to delete all content, expired to delete only expired content. Example
Optional for job start_date To constrain deleted content to a date range (by publish date) you must specify both a start_date and an end_date. Content published on or after the specified start_date is included in the range, but only those dates prior to the end_date are included in the range. Compatible format: YYYY-MM-DD. Example
 Optional for job end_date To constrain deleted content to a date range (by publish date) you must specify both a start_date and an end_date. Content published on or after the specified start_date is included in the range, but only those dates prior to the end_date are included in the range. Compatible format: YYYY-MM-DD.

delete_content Examples

delete_content Example
POST MODE
Type Parameter
Required For delete_content type
Example
Delete all content:
{
 "job" : "delete_content",
 "type" : "all"
}
Delete all expired content:
{
 "job" : "delete_content",
 "type" : "expired"
}
delete_content Example 2
POST MODE
Type Parameter
Required For delete_content type
Optional For delete_content start_date, end_date
Example
Delete all content published in the last 6 months of 2016 including on the specified dates:
{
 "job" : "delete_content",
 "type" : "all",
 "start_date" : "July 1, 2016",
 "end_date" : "Dec 31, 2016"
}
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"
}

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

 

Job HTTP Code Error Code Error Message Notes
list_erase 200 99 The lists parameter must be passed as an array
list_erase 200 99 Request exceeds limit of 1,000 lists. No lists deleted
File Import jobs content_update purchase_import import 400 99 File Parameter is required
File Import jobs content_update purchase_import import 400 99 The size of the file exceeds the maximum upload file size Max upload is 1gb
File Import jobs content_update purchase_import import 400 99 Failed to upload file
File Import jobs content_update purchase_import import 400 99 Unable to determine the size of the file Might not be reachable error
File Import jobs content_update purchase_import import 400 99 File not set Might not be reachable error
400 99 Invalid JSON provided