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

    Perform a bulk update of any number of user profiles. Use this to generate a list for any user matching a query, opt out a large list of email addresses, add a variable to a group of users, and more.

    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. update job Notes:
    • The update postback does not trigger from the bulk update job, only from a user management page.
    • Best when updating a large number of profiles, such as updating optout preferences or variables
    • Supports JSON files
    • The update job processes more slowly than the import job
    • If you want to apply the same update to all of the users specified, you should pass the update parameter.
    • You must pass one of the required parameters, but not more than one: emails, url, file, or query

    Endpoint URL: https://api.sailthru.com/<span style="color: #333399;">job</span>

    You'll specify update 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 Marigold Engage 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

    update

    Type Parameter Description Example
    Required for job url URL to pull data from
    • If you are using the url or file parameters, then you are pulling data from a url or file. There are two different formats you can use:
      • Simple - Email address per line. This lets you perform the same update on a list of users.
      • JSON - JSON object per line. This lets you specify individual updates on a per-user basis. Each line should contain a JSON object with the email element to identify the user, and any optional parameters: vars, lists, or optout.
    		 Example call Example JSON file
    Required for job file File data to upload
    • The maximum upload file size is 1 GB
    • If you are using the url or file parameters, then you are pulling data from a url or file. There are two different formats you can use:
      • Simple - Email address per line. This lets you perform the same update on a list of users.
      • JSON - JSON object per line. This lets you specify individual updates on a per-user basis. Each line should contain a JSON object with the email element to identify the user, and any optional parameters: vars, lists, or optout.
    Required for job query A query or search Queries In The API Example
    Optional for job update[vars] The key/value hash of vars to set Example
    Optional for job update[lists] The key/value hash of lists to subscribe or unsubscribe to. 1 means subscribe, and 0 means unsubscribe. Example
    Optional for job update[optout] Updates a user's optout level
    • Valid optout values:
      • all - Opts users out of all communications
      • basic - Opts the user out of all communications except templates marked as "basic"
      • none - Opts the user back in
    FURTHER INFORMATION: User Opt-Out Levels    		 Example
    Optional for job update[delete_vars] An array of vars to delete from user profiles
    • This process is irreversible, so proceed with caution
    		 Example
    Optional for job signup_date Use JSON to update users or a user's signup_date. Can also be passed along with these optional parameters: vars, lists or optout. Example

    update Examples

    url Required
    POST MODE
    Type Parameter
    Required For update url
    Example 
    {
    "job":"update",
    "url":"https://example.com"
}
    See also: Bulk update JSON file example.
    JSON Example
    POST MODE
    Type Parameter
    Optional For update N/A
    Example
    Example content of JSON file for bulk update, sent with an update call or referenced by URL: 
    {"id":"user1@example.com", "keys":{"extid":"12"}, "fields":{"keys":1}, "vars":{"updated":"yes"}, "lists":{"Update List":1}}
{"id":"user2@example.com", "keys":{"extid":"13"}, "fields":{"keys":1}, "lists":{"Update List":0}}
{"id":"user3@example.com", "keys":{"extid":"14"}, "fields":{"keys":1}, "optout":"all"}
{"id":"user4@example.com", "signup_date":"1987-08-01"}
    Object 1: Adding a key, adding a var, adding to a list Object 2: Adding a key, removing from a list Object 3: Adding a key, setting status to optout all Object 4: Setting custom signup date Click here to view the same content in an easier-viewed but unsupported format.
    {
   "id":"user1@example.com",
   "keys":{"extid":"12"},
   "fields":{"keys":1},
   "vars":{"updated":"yes"},
   "lists":{"Update List":1}
}
{
   "id":"user2@example.com",
   "keys":{"extid":"13"},
   "fields":{"keys":1},
   "lists":{"Update List":0}
}
{
   "id":"user3@example.com",
   "keys":{"extid":"14"},
   "fields":{"keys":1},
   "optout":"all"
}
{
   "id":"user4@example.com",
   "signup_date":"1987-08-01"
}
    query Required
    POST MODE
    Type Parameter
    Required For update query
    Example 
    {
    "job":"update",
    "query":
        {
            "source_list":"Main",
            "criteria":["engagement_min"],
            "engagement":[5]
        }
}
    vars Optional
    POST MODE
    Type Parameter
    Optional For update update[vars]
    Example 
    {
    "job":"update",
    "query":{"source_list":"Main"},
    "update":
    {
        "vars":
        {
            "name":"Joe One",
            "company":"Example Company"
        }
    }
}
    lists Optional
    POST MODE
    Type Parameter
    Optional For update update[lists]
    Example 
    {
    "job":"update",
    "query":{"source_list":"Main"},
    "update":
        {
            "lists":
                {
                    "Main-copy":1
                }
        }
}
    optout Optional
    POST MODE
    Type Parameter
    Optional For update update[optout]
    Example 
    {
    "job":"update",
    "query":{"source_list":"mylistname"},
    "update":{"optout":"all"}
}
    deletevars Optional
    POST MODE
    Type Parameter
    Optional For update update[delete_vars]
    Example 
    {
    "job":"update",
    "query":
        {
            "source_list":"Main"
        },
    "update":
        {
            "delete_vars":
                [
                    "name",
                    "company"
                ]

        }
}
    signup_date Optional
    POST MODE
    Type Parameter
    Optional For update signup_date
    Example 
    {"email":"someone@somedomain.com", "signup_date":"Jan 18, 2013"}

    Use Cases

    Add Users to a New List

    {"job":"update","report_email":"myemail@mydomain.com","query":{"source_list":"Main"},"update":{"lists":{"Main-copy":1}}}
    This adds all the users on the list "Main" to a new list called "Main-copy."
    Add Users to a List using a URL File (in PHP)
    $report_email = "reportemail@domain.com";
$url = "https://www.urlhere.com";
$client->processUpdateJobFromUrl($url, array("lists"=>array("listnamegoeshere"=>1)), $report_email ,  false)

    Bulk Update Optout Status for a List

    {'job':'update','query':{'source_list':'mylistname'},'update':{'optout':'all'}}

    Query Users and Add Segment to a New List

    {"job":"update","report_email":"myemail@mydomain.com","query":{"source_list":"Main","criteria:["engagement_min"],"engagement":[5]},"update":{"lists":{"Main-copy":1}}}
    This query checks for users on the list "Main" that have an engagement level of at least 5, and then adds those users to a new list called "Main-copy."

    Query Users on Multiple Lists and Add Segment to a New List

    {"job":"update","report_email":"myemail@mydomain.com","query":{"source_list":".multiple","multiple_source_list":["Main","Another List"],"criteria:["engagement_min"],"engagement":[5]},"update":{"lists":{"My Copy":1}}}
    This query checks for users on the lists "Main" and "Another List" that have an engagement level of at least 5, and then adds those users to a new list called "My Copy."

    Set Vars on a Group of Users

    Find all users on the list Main who have an email address at example.com and who open email more than 50% of the time in the state of NY. Add a var to those users called "is_example" and set the value as true. Example in JSON: 
    {"job":"update","report_email":"me@mydomain.com",
"query":{
   "source_list":"Main",
   "criteria":["domain","geo_state"],
   "value":["example.com","NY US"],
   "geo_frequency":[null,50]
   },
"update":{"vars":{"is_example":1}
   }
}

    Third-Party Opt-out

    You are working with a third party that is able to get you occasional exports of email addresses that need to be opted out. Take the list of third party email addresses and turn them into a new line-separated list of emails, then put them on a private URL and: 
    $sailthru->apiPost('job', array(
  'job' => 'update',
  'url' => 'https://path/to/emails',
  'update' => array('optout' => 'blast'),
));
    Or POST directly as a file: 
    $sailthru->apiPost('job', array(
  'job' => 'update',
  'update' => array('optout' => 'blast'),
), array(
  'file' => '/path/to/emails',
));

    Regular List Cleaning

    You want to automatically remove disengaged users from your main  list and move them onto a disengaged  list. (You could achieve a similar effect by just using Smart Lists, but let's assume for some reason you need to use normal lists.) 
    $sailthru->apiPost('job', array(
  'job' => 'update',
  'query' => array('source_list' => 'main',
                   'criteria' => array('engagement_max'),
                   'engagement' => array(2)),
  'update' => array('lists' => array('main' => 0, 'disengaged' => 1)),
));

    Multiple Source Lists

    You can query multiple lists at the same time. Use multiple source lists within the JOB call, 'update' type. For example: 
    ("job",{"job"=>"update","report_email"=>"joe@example.com","query"=>{"source_list"=>".multiple", "multiple_source_list" => ["listname1","listname2"]}, "update"=>{"name of merged list" => 1}})

    General JSON File Requirements

    Each job that requires a JSON file shares some general file requirements. See the specific jobs for all the file requirements.
    • The file must be a text file, a UTF-8 text file, or a CSV file
    • One JSON object per line
    • The maximum upload size is 1GB

    Error Codes

    Job HTTP Code Error Code Error Message Notes
    update 400 99 One of the following parameters is required: emails, url, file, or query
    update 400 99 List name: {LIST_NAME} failed validation
    update 400 99 List name cannot contain a $ character
    update 400 99 Invalid URL:
    update When using a file, same errors applies as import job
      400 99 Invalid JSON provided  
    Top