job
Contents
Introduction
Start a background job, such as a data import or export, or get its status or result.
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
Job Types
The following jobs are available.
- blast_query – Export a csv of campaign recipients, including their profile ID, hashed email address, and open/click data.
- blast_save_list – Query your users that received a specific campaign, and save that new segment to a new or existing natural list.
- blast_snapshot – Query your users to see who received a specific campaign, and generate a detailed snapshot of their analytics.
- content_update – Create or Update content from a JSON file.
- delete_content – Remove content from your Sailthru 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.
- export_list_data – Export all the users from a list including their data in CSV format.
- export_purchase_log – Export a chronological record of purchases in CSV format.
- export_scheduled_sends – Download a CSV report of all currently-scheduled transactional sends.
- import – Import a number of email addresses into a natural list.
- Best when importing a large data set with a consistent variable structure, like a file for a new list
- Supports CSV
- Each client ID is limited to a maximum of 5 running import jobs
- list_erase – Delete one or more lists by name.
- snapshot – Query your users and generate a detailed snapshot of their analytics (similar to the Snapshot Report in the Sailthru interface).
- update – Perform a bulk update of any number of user profiles. You can 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.
- Best when updating a large number of profiles, such as updating optout preferences or variables
- Supports JSON files
- There is no limit to the number of running update jobs
Note: The update postback does not trigger from the bulk update job, only from a user management page.
- purchase_import – Updates historical purchase data
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 ajob
GET call), with two additional parameters that are provided by Sailthru – yourapi_key
and the uniquesig
for the request, so that it can be optionally verified as a legitimate Sailthru 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 Sailthru request |
Job Parameter Values
Submit one as the job value to indicate the job type. Then, include the additional parameters required by that job type.
Value | Description | Additional Parameters for Job Type |
---|---|---|
blast_query |
Export list of campaign recipients data in CSV format. | Parameters |
blast_save_list |
Query your users that received a specific campaign, and save that new segment to a new or existing natural list. | Parameters |
blast_snapshot |
Query your users to see who received a specific campaign, and generate a detailed snapshot of their analytics (similar to the Snapshot Report in the Sailthru interface). | Parameters |
content_update |
Create or Update content from a JSON file. | Parameters |
export_list_data |
Export user data from a list in CSV format. | Parameters |
export_purchase_log |
Export user data from a list in CSV format. | Parameters |
export_scheduled_sends |
Download a CSV report of all currently-scheduled transactional sends. No additional parameters are required | N/A |
import |
Import a number of email addresses into a natural list. | Parameters |
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. |
N/A |
purchase_import |
Update historical purchase data. | Parameters |
snapshot |
Query your users and generate a detailed snapshot of their analytics (similar to the Snapshot Report in the Sailthru interface). | Parameters |
update |
Perform a bulk update of any number of user profiles. You can 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.
|
Parameters |
Job-Specific Parameters
blast_query
Example Call
{
"job":"blast_query",
"blast_id":"8305513"
}
Example Response
{
"job_id" : "584848516e4adcbb238b46e8",
"name" : "Export Mass Mail Data",
"status" : "completed",
"start_time" : "Wed, 07 Dec 2016 12:35:14 -0500",
"end_time" : "Wed, 07 Dec 2016 12:35:25 -0500",
"filename" : "export-blast-8305513.csv",
"export_url" : "https://s3.amazonaws.com/sailthru/export/2016/12/07/a3ba0404814dbfa76fb24c6c99111111",
"blast_id" : 8305513
}
Type | Parameter | Description | Example |
---|---|---|---|
Required for job type | blast_id |
A valid blast identification | Example |
Return for job type | export_url |
A URL pointing to the exported data. The link expires after 2 hours.
|
Example |
Return for job type | filename |
The generated file name | Example |
blast_save_list
Example - Minimum Parameters
{
"job":"blast_save_list",
"blast_id":123456,
"query":
{
"source_list":"Main",
"criteria":["engagement_min"],
"engagement":[5]
},
"list":"Opened-Jun-15-Campaign"
}
Example Response
{
"job_id" : "58484c9fe661f072558b47fa",
"name" : "Opened-Jun-15-Campaign",
"status" : "completed",
"start_time" : "Wed, 07 Dec 2016 12:53:36 -0500",
"end_time" : "Wed, 07 Dec 2016 12:53:36 -0500"
}
This example represents a job that has reached completed
status. See How It Works, above, for more information.
Example - Additional Parameters
{
"job":"blast_save_list",
"blast_id":123456,
"query":
{
"source_list":"Main",
"criteria":["engagement_min"],
"engagement":[5]
},
"list":"Opened-Jun-15-Campaign"
"report_email":"example@sailthru.com"
}
Example Response
{
"job_id" : "5848501ce661f094558b4aa6",
"name" : "Opened-Jun-15-Campaign",
"report_email" : "example@sailthru.com",
"status" : "completed",
"start_time" : "Wed, 07 Dec 2016 13:08:31 -0500",
"end_time" : "Wed, 07 Dec 2016 13:08:31 -0500"
}
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 | blast_id |
Identification of the blast you wish to take a snapshot of | Example |
Required for job | query |
A query or search Queries In The API |
Example |
Required for job | list |
The name of the list to add users to (if it does not exist, it will be created)
|
Example |
Optional for job | report_email |
Receive an email notification when a job is complete job Examples |
Example |
blast_snapshot
Example
{
"job":"blast_snapshot",
"query":
{
"source_list":"Main",
"criteria":["engagement_min"],
"engagement":[5]
},
"blast_id":"190940"
}
Show Example Response{
"job_id" : "5848546e15dd9634628b473e",
"name" : "Campaign Snapshot: Sample Campaign, Campaign recipients: engagement level is at least active",
"status" : "completed",
"start_time" : "Wed, 07 Dec 2016 13:26:56 -0500",
"end_time" : "Wed, 07 Dec 2016 13:26:57 -0500",
"total" : {
"count" : 3
},
"engagement" : {
"new" : {
"count" : 3,
"name" : "new"
}
},
"domain" : [
{
"count" : 3,
"name" : "sailthru.com"
}
],
"device" : [],
"signup" : {
"201606" : {
"count" : 3,
"name" : "201606"
}
},
"subject" : [
{
"count" : 3,
"name" : "asdf"
}
],
"smtp" : [
{
"count" : 2,
"name" : "nj1-mta-1.flt"
},
{
"count" : 1,
"name" : "nj1-mta-18.flt"
}
],
"click_times" : [],
"click_total_times" : [],
"beacon_times" : [],
"beacon_total_times" : [],
"purchase_times" : [],
"clickmap" : [],
"urls" : [],
"topusers" : [
{
"email" : "user1@sailthru.com",
"click_url" : null,
"click_total" : 0,
"open_total" : 0,
"click_time" : null,
"open_time" : null,
"pv" : null,
"rev" : 0,
"score" : 0
},
{
"email" : "user2@sailthru.com",
"click_url" : null,
"click_total" : 0,
"open_total" : 0,
"click_time" : null,
"open_time" : null,
"pv" : null,
"rev" : 0,
"score" : 0
},
{
"email" : "user3@sailthru.com",
"click_url" : null,
"click_total" : 0,
"open_total" : 0,
"click_time" : null,
"open_time" : null,
"pv" : null,
"rev" : 0,
"score" : 0
}
],
"banners" : [],
"purchase_items" : [],
"groups" : []
}
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 | query |
A query or search Queries In The API |
Example |
Required for job | blast_id |
A valid blast identification | Example |
Return for job | stats |
Data structure containing the results of the snapshot | N/A |
content_update
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 |
delete_content
Delete All
{
"job" : "delete_content",
"type" : "all"
}
Delete All Expired
{
"job" : "delete_content",
"type" : "expired"
}
Delete All in Range
{
"job" : "delete_content",
"type" : "all",
"start_date" : "2016-07-01",
"end_date" : "2016-12-31"
}
Delete Expired in Range
{
"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. |
export_purchase_log
Type | Parameter | Description | Example |
---|---|---|---|
Required for job | start_date |
Purchase report’s start date
|
Example |
Required for job | end_date |
Purchase report’s end date | Example |
export_list_data
Example - Min. Parameters
{
"job": "export_list_data",
"list": "example list"
}
Example with Optional Fields & SHA256 Hashing
{
"job" : "export_list_data",
"list" : "example list",
"hash_algo" : "sha256",
"fields" : {
"geolocation_city" : 1,
"geolocation_zip" : 1,
"last_click" : 1,
"opens" : 1,
}
}
Type | Parameter | Description | Example |
---|---|---|---|
Required for job | list |
Name of the list to export | Example |
Optional for job | hash_algo |
The algorithm to use for the hash of each user’s email address in the export file’s ‘hash’ column. The default algorithm is MD5. Set hash_algo to sha256 to use SHA256, instead. |
n/a |
Optional for job | fields |
The field(s) of data to export. Note:
|
Example |
import
Emails (Directly)
{
"job":"import",
"list":"List 1",
"emails":"user1@sailthru.com,user2@sailthru.com,user3@sailthru.com"
}
File (Upload)
{
"job":"import",
"list":"List 1",
"file":"/tmp/users.txt"
}
URL
{
"job":"import",
"list":"List 1",
"url":"https://s3.amazonaws.com/sailthru-static/users.csv"
}
Response
{
"job_id" : "58487498e9328b50588b4b54",
"name" : "List Import: List 1",
"list" : "List 1",
"error" : false,
"status" : "completed",
"start_time" : "Wed, 07 Dec 2016 15:44:09 -0500",
"end_time" : "Wed, 07 Dec 2016 15:44:10 -0500"
}
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 | list |
The name of the list to import to (if it does not exist, it will be created).
|
Example |
Required for job | emails |
Emails to upload to the list | Example |
Required for job | file |
File data to upload as a list. Note:
|
Example |
Required for job | url |
URL to pull data from | Example |
Optional for job | signup_dates |
This parameter is for updating custom signup dates.
|
Example |
purchase_import
Example Call
{
"job":"purchase_import",
"file":"/tmp/file.txt"
}
Type | Parameter | Description | Example |
---|---|---|---|
Required for job | file |
UTF-8 text file containing JSON objects.
Note: Active Lifecycle Optimizer flows with “Made Purchase” entries will include purchases added from this job type. Turn off any purchase-based Lifecycle Optimizer flows temporarily while running the |
Example |
snapshot
Example Call
{
"job":"snapshot",
"query":
{
"source_list":"",
"criteria":["domain"],
"value":"sailthru.com"
}
}
Show response{
"job_id" : "584899e9e9328ba90a8b479b",
"name" : "Snapshot: All users: email domain is s",
"status" : "completed",
"start_time" : "Wed, 07 Dec 2016 18:23:23 -0500",
"end_time" : "Wed, 07 Dec 2016 18:23:44 -0500",
"snapshot" : {
"browsers" : [],
"cities" : [],
"countries" : [],
"engagement" : [],
"engagement_by_month" : [],
"engagement_by_domain" : [],
"horizon" : [],
"hours" : {
"00" : 0,
"11" : 0,
"22" : 0,
"01" : 0,
"12" : 0,
"23" : 0,
"02" : 0,
"13" : 0,
"03" : 0,
"14" : 0,
"04" : 0,
"15" : 0,
"05" : 0,
"16" : 0,
"06" : 0,
"17" : 0,
"07" : 0,
"18" : 0,
"08" : 0,
"19" : 0,
"09" : 0,
"20" : 0,
"10" : 0,
"21" : 0
},
"interested" : [],
"lists" : [],
"purchase_counts" : [],
"purchase_prices" : [],
"site_hours" : {
"00" : 0,
"11" : 0,
"22" : 0,
"01" : 0,
"12" : 0,
"23" : 0,
"02" : 0,
"13" : 0,
"03" : 0,
"14" : 0,
"04" : 0,
"15" : 0,
"05" : 0,
"16" : 0,
"06" : 0,
"17" : 0,
"07" : 0,
"18" : 0,
"08" : 0,
"19" : 0,
"09" : 0,
"20" : 0,
"10" : 0,
"21" : 0
},
"top_purchase_items" : [],
"total_count" : 0,
"total_purchase_price" : 0,
"total_purchasers" : 0
}
}
This example represents a job that has reached completed
status. See How It Works, above, for more information.
snapshot | |||
---|---|---|---|
Type | Parameter | Description | Example |
Required for job | query |
A query or search Queries In The API |
Example |
Return for job | query |
Data structure containing the query | N/A |
Return for job | snapshot |
Data structure containing the results of the snapshot | N/A |
update
Type | Parameter | Description | Example |
---|---|---|---|
Required for job | url |
URL to pull data from
|
Example call Example JSON file |
Required for job | file |
File data to upload
|
Example JSON file |
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
FURTHER INFORMATION: |
Example |
Optional for job | update[delete_vars] |
An array of vars to delete from user profiles
|
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 |
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
Parameter Examples
GET MODE | ||
---|---|---|
Type | Parameter | |
Required | job_id |
|
Example | ||
|
GET MODE | ||
---|---|---|
Type | Parameter | |
Return | N/A | |
Example | ||
|
POST MODE | ||
---|---|---|
Type | Parameter | |
Required | job |
|
Example | ||
|
POST MODE | ||
---|---|---|
Type | Parameter | |
Required For ad_inventory |
start_date |
|
Example | ||
POST MODE | ||
---|---|---|
Type | Parameter | |
Required For ad_inventory |
end_date |
|
Example | ||
POST MODE | ||
---|---|---|
Type | Parameter | |
Required For blast_query |
blast_id |
|
Example | ||
|
POST MODE | ||
---|---|---|
Type | Parameter | |
Return For blast_query |
filename |
|
Example | ||
|
POST MODE | ||
---|---|---|
Type | Parameter | |
Return For blast_query |
export_url |
|
Example | ||
|
POST MODE | ||
---|---|---|
Type | Parameter | |
Required For blast_save_list |
blast_id |
|
Example | ||
|
POST MODE | ||
---|---|---|
Type | Parameter | |
Required For blast_save_list |
query |
|
Example | ||
|
POST MODE | ||
---|---|---|
Type | Parameter | |
Required For blast_save_list |
list |
|
Example | ||
|
POST MODE | ||
---|---|---|
Type | Parameter | |
Optional For blast_save_list |
report_email |
|
Example | ||
|
POST MODE | ||
---|---|---|
Type | Parameter | |
Required For blast_snapshot |
query |
|
Example | ||
POST MODE | ||
---|---|---|
Type | Parameter | |
Required For blast_snapshot |
blast_id |
|
Example | ||
|
POST MODE | ||
---|---|---|
Type | Parameter | |
Required For content_update |
file |
|
Example | ||
Call
File content
|
POST MODE | ||
---|---|---|
Type | Parameter | |
Required For delete_content |
type |
|
Example | ||
Delete all content:
Delete all expired content:
|
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:
Delete only expired content published in the last 6 months of 2016 including the specified dates:
|
POST MODE | ||
---|---|---|
Type | Parameter | |
Required For export_list_data |
list |
|
Example | ||
|
POST MODE | ||
---|---|---|
Type | Parameter | |
Optional For export_list_data |
fields |
|
Example | ||
|
Example Call
{
"job":"export_purchase_log",
"start_date":20160101,
"end_date":20160131
}
Example Response
{
"job_id" : "58486fa1e661f07c198b45f6",
"name" : "Export purchase logs from 20160101 to 20160131",
"status" : "completed",
"start_time" : "Wed, 07 Dec 2016 15:22:58 -0500",
"end_time" : "Wed, 07 Dec 2016 15:23:04 -0500",
"filename" : "purchase_log-20160101-20160131.csv",
"export_url" : "https://s3.amazonaws.com/sailthru/export/2016/12/07/d699e4bd562eec65a1e0c2f47b111111"
}
This example represents a job that has reached completed
status. See How It Works, above, for more information.
POST MODE | ||
---|---|---|
Type | Parameter | |
Required For export_purchase_log |
start_date , end_date |
|
Example | ||
|
POST MODE | ||
---|---|---|
Type | Parameter | |
Required For import |
list |
|
Example | ||
|
POST MODE | ||
---|---|---|
Type | Parameter | |
Required For import |
emails |
|
Example | ||
|
POST MODE | ||
---|---|---|
Type | Parameter | |
Required For import |
file |
|
Example | ||
|
POST MODE | ||
---|---|---|
Type | Parameter | |
Required For import |
url |
|
Example | ||
|
POST MODE | ||
---|---|---|
Type | Parameter | |
Optional For import |
signup_dates |
|
Example | ||
|
POST MODE | ||
---|---|---|
Type | Parameter | |
Required For snapshot |
query |
|
Example | ||
|
POST MODE | ||
---|---|---|
Type | Parameter | |
Required For update |
url |
|
Example | ||
See also: Bulk update JSON file 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:
Object 1: Adding a key, adding a var, adding to a list
|
POST MODE | ||
---|---|---|
Type | Parameter | |
Required For update |
query |
|
Example | ||
|
POST MODE | ||
---|---|---|
Type | Parameter | |
Optional For update |
update[vars] |
|
Example | ||
|
POST MODE | ||
---|---|---|
Type | Parameter | |
Optional For update |
update[lists] |
|
Example | ||
or
|
POST MODE | ||
---|---|---|
Type | Parameter | |
Optional For update |
update[optout] |
|
Example | ||
|
POST MODE | ||
---|---|---|
Type | Parameter | |
Optional For update |
update[delete_vars] |
|
Example | ||
|
POST MODE | ||
---|---|---|
Type | Parameter | |
Optional For update |
signup_date |
|
Example | ||
|
POST MODE | ||
---|---|---|
Type | Parameter | |
Required For purchase_import |
file |
|
Example | ||
Call JSON
File Content (Supported format: one object per line) {"email":"user1@example.com","date":"2016-06-01","purchase_keys":{"extid":"purchase101"},"items":[{"qty":1,"id":"2005","title":"T-Shirts in Black","url":"http://example.com/products/tshirts-black","price":4000,"tags":["shirts","under100","color-black"],"vars":{"sailthru_category":"clothing"},"image":"http://email-media.s3.amazonaws.com/Sailthru/default/images/stock/t-shirts.jpg"},{"qty":1,"id":"SKU1002","title":"Women's Shoes in Black and White","url":"http://example.com/products/womens-shoes-in-black","price":25000,"tags":["shoes","footwear","formalwear","womens","color-black"],"vars":{"sailthru_category":"shoes"},"image":"http://email-media.s3.amazonaws.com/Sailthru/default/images/stock/high_heels.jpg"},{"qty":2,"id":"SKU1001","title":"Men's Shoes in Black","url":"http://example.com/products/mens-shoes-in-black","price":10000,"tags":["shoes","footwear","formalwear","mens","color-black"],"vars":{"sailthru_category":"shoes"},"image":"http://email-media.s3.amazonaws.com/Sailthru/default/images/stock/black_mens_shoes.jpg"}],"vars":{"order_level_var":"abcd1234"},"adjustments":[{"price":-5000,"title":"Sale"},{"price":-2000,"title":"coupon"}]} {"email":"user2@example.com","date":"2016-06-02","purchase_keys":{"extid":"purchase202"},"items":[{"qty":2,"id":"2005","title":"T-Shirts in Black","url":"http://example.com/products/tshirts-black","price":4999,"tags":["shirts","under100","color-black"],"vars":{"sailthru_category":"clothing","item_level_var":"promotional_item"},"image":"http://email-media.s3.amazonaws.com/Sailthru/default/images/stock/t-shirts.jpg"}],"vars":{"order_level_var":"efhg6789"},"tenders":[{"price":"9998","title":"Discover"}]} {"email":"user3@example.com","date":"2016-06-03","purchase_keys":{"extid":"purchase303"},"items":[{"qty":1,"id":"SKU1002","title":"Women's Shoes in Black and White","url":"http://example.com/products/womens-shoes-in-black","price":24900,"tags":["shoes","footwear","formalwear","womens","color-black"],"vars":{"sailthru_category":"shoes"},"image":"http://email-media.s3.amazonaws.com/Sailthru/default/images/stock/high_heels.jpg"},{"qty":1,"title":"Men's Shoes in Black","id":"SKU1001","url":"http://example.com/products/mens-shoes-in-black","price":19999,"tags":["shoes","footwear","formalwear","mens","color-black"],"vars":{"sailthru_category":"shoes"},"image":"http://email-media.s3.amazonaws.com/Sailthru/default/images/stock/black_mens_shoes.jpg"}],"vars":{"order_level_var":"shoes_purchase"},"adjustments":[{"price":2500,"title":"Express Shipping"}]}Click here to view the same content in an easier-viewed but unsupported format.
|
POST MODE | ||
---|---|---|
Type | Parameter | |
Optional | report_email |
|
Example | ||
|
POST MODE | ||
---|---|---|
Type | Parameter | |
Optional | postback_url |
|
Example | ||
|
Additional Examples and 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 the Optout Status of a List of Users
{'job':'update','query':{'source_list':'mylistname'},'update':{'optout':'all'}}
Query Users and Add That 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 That 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.”
Query a Campaign and Add Those Users to a List
Example in PHP:
$sailthru->apiPost('job', array(
'job' => 'blast_save_list',
'blast_id' => '123456',
'query' => array('criteria' => array('match'), 'field' => array('gender'), 'value' => array('male')),
'list' => 'male list'
));
Example in JSON:
{"job":"blast_save_list","blast_id":"1234567","list":"My List","query":{"criteria":["valid"]}}
Set Custom Signup Date on a New/Existing Group of Users
Upload a CSV of new or existing users using the “import” parameter of the Job call, and set a custom signup date on these users. Note that the CSV must have two columns: email
and signup_date
. Additionally, the “signup_dates
” parameter must be passed in the call with a value of 1
or true
.
Example in PHP:
$api_client = new Sailthru_Client($client_api_key, $client_secret, $api_url);
$api_client.apiPost("job", array("job" => "import", "list" => "test_list", "signup_dates" => "true", "file" => "hello.csv"), array('file'));
Example in Ruby:
sc = Sailthru::SailthruClient.new("123456789101112131415","123456789101112131415","https://api.sailthru.com")
sc.api_post(:job, {"job"=>"import","list"=>"test2","signup_dates"=>true,"file"=>"hello.csv"}, "file")
Set Vars on a Group of Users
Find all users on the list Main who have an email address at sailthru.com and who open email more than 50% of the time in the state of NY. Add a var to those users called “is_sailthru” 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":["sailthru.com","NY US"],
"geo_frequency":[null,50]
},
"update":{"vars":{"is_sailthru":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 on Sailthru.
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',
));
Populating Campaign With Per-User Data
You want to send a campaign which has a section showing how many new friends have joined the site per-user. You want to send the campaign as soon as possible after the data transfer is complete.
Create a JSON-format file with the users, setting a variable for each one, like so:
{"email":"foo@example.com","vars":{"new_friends":["Ian","Will","Praj","Eli","Emily"]}}
{"email":"bar@example.com","vars":{"new_friends":["Neil","John"]}}
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}})
Error Codes
Job | HTTP Code | Error Code | Error Message | Notes |
---|---|---|---|---|
blast_query | 400 | 2 | Missing required parameter: blast_id | |
blast_query | 404 | 13 | Unknown blast_id | |
blast_query | 403 | 99 | You may not export a blast that has been sent | |
blast_query | 400 | 99 | Blasts stats are not available yet for {BLAST_ID} so this job cannot begin. Please try again shortly | |
blast_save_list | 400 | 2 | Missing required parameter: blast_id/query/list | |
blast_save_list | 200 | 99 | Invalid list name: | |
blast_save_list | 400 | 13 | Invalid blast_id | |
blast_save_list | 400 | 99 | Blasts stats are not available yet for {BLAST_ID} so this job cannot begin. Please try again shortly | |
blast_snapshot | 400 | 13 | Invalid blast_id | |
blast_snapshot | 400 | 99 | Blasts stats are not available yet for {BLAST_ID} so this job cannot begin. Please try again shortly | |
export_list_data | 400 | 2 | Missing required parameter: list | |
export_list_data | 404 | 99 | List not found | |
export_purchase_log | 400 | 18 | Missing required parameter: start_date,end_date | |
export_purchase_log | 400 | 18 | Invalid start_date/end_date fromat | |
export_purchase_log | 400 | 18 | Invalid date range. Start Date canot be later than End Date | |
export_purchase_log | 400 | 18 | Invalid date range. Up to 31 days allowed but {day_range} given | Start_date and end_date too far apart |
import | 400 | 2 | Missing required parameter: list | |
import | 200 | 99 | Invalid list name: | |
import | 400 | 99 | One of the following parameters is required: emails, url, or file | |
import | 400 | 99 | Invalid URL | |
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 |
snapshot | 400 | 2 | Missing required parameter: query,update | |
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 |