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.

If an email address does not currently exist, a new user profile will be created.

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

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

update

update Examples

url Required

{
    "job":"update",
    "url":"https://example.com"
}

JSON Example

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

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

{
    "job":"update",
    "query":
        {
            "source_list":"Main",
            "criteria":["engagement_min"],
            "engagement":[5]
        }
}

vars Optional

{
    "job":"update",
    "query":{"source_list":"Main"},
    "update":
    {
        "vars":
        {
            "name":"Joe One",
            "company":"Example Company"        }
    }
}

lists Optional

{
    "job":"update",
    "query":{"source_list":"Main"},
    "update":
        {
            "lists":
                {
                    "Main-copy":1
                }
        }
}

optout Optional

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

deletevars Optional

{
    "job":"update",
    "query":
        {
            "source_list":"Main"        },
    "update":
        {
            "delete_vars":
                [
                    "name",
                    "company"                ]

        }
}

signup_date Optional

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

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

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

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