For Developers Overview
  • API Basics
    Introduction to the API API Technical Details API Postbacks User Queries for Job and List API Error and Response Codes API Test Page
  • API Endpoints
  • API Client Libraries
    API Client Libraries Overview Java Library JavaScript API Library .NET Library Node.js Library Perl Library PHP5 Library Python Library Ruby Library
  • Zephyr Guide
    Zephyr Overview Common Zephyr Examples Zephyr Examples Library Zephyr Template Variables Zephyr Expressions And Operators Zephyr Control Structures Zephyr Assignment Operator For Variables Single Vs. Double Braces “Profile” Object “Message” Object “Blast” Object “Feed” Object Link Rewriting With Zephyr Set User Vars or List Membership On-Click with URL Parameters Forward To A Friend
  • Zephyr Functions
    Zephyr Functions Index abs ad adinfo api_event api_send api_user append_user_var assert base64_decode base64_encode bucket_list cancel compare contains content_intersect date dedupe distance exp filter filter_content first h horizon_count horizon_interest horizon_select horizon_set_interest int intersect join keys length list(function) lower load_content map md5 message_id number personalize promotion public_share push random range replace round set sha1 sha256 shuffle signup_confirm slice social_share sort split sqrt strip_tags strpos strrpos substr text time title type u upper user_engagement user_geo_home user_geo_select_region values
  • Zephyr Tutorial
    Zephyr Tutorials Lesson 1: Zephyr Basics Lesson 2: Data Basics
  • Content Triggers
    Content Triggers

    • 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/<span style="color: #333399;">job</span>

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

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

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

    Contact us

    Top