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.

TypeParameterDescriptionExample
Required for jobfileText 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
TypeParameter
Required For content_updatefile
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"}v

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

 

TypeParameterDescriptionExample
Required for jobtypeall to delete all content, expired to delete only expired content.Example
Optional for jobstart_dateTo 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 jobend_dateTo 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
TypeParameter
Required For delete_contenttype
Example
Delete all content:
{
 "job" : "delete_content",
 "type" : "all"}
Delete all expired content:
{
 "job" : "delete_content",
 "type" : "expired"}

delete_content Example 2
POST MODE
TypeParameter
Required For delete_contenttype
Optional For delete_contentstart_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

JobHTTP CodeError CodeError MessageNotes
list_erase20099The lists parameter must be passed as an array
list_erase20099Request exceeds limit of 1,000 lists. No lists deleted
File Import jobs content_update purchase_import import40099File Parameter is required
File Import jobs content_update purchase_import import40099The size of the file exceeds the maximum upload file size Max upload is 1gb
File Import jobs content_update purchase_import import40099Failed to upload file
File Import jobs content_update purchase_import import40099 Unable to determine the size of the fileMight not be reachable error
File Import jobs content_update purchase_import import40099File not setMight not be reachable error
40099Invalid JSON provided