job – Import and Export

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

Import and Export jobs

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
- The import job processes faster than the update job
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 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

export_list_data

Export user data from a list in CSV format.

Example Min. Parameters

To request all fields. Including optional parameters will limit the fields returned.

Copy

{
"job": "export_list_data",
"list": "example list"  
}

Example with Optional Fields & SHA256 Hashing

This example requests some of the optional user fields and requests that user email addresses are hashed with the SHA256 algorithm.

Copy

{
   "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: The exported URL contains PII hashed data. Using the `fields` parameter limits the CSV export to those specific fields (in addition to Profile ID and Email Hash). Valid `fields` values: `clicks` `domain` `email_message` `email_status` `email_status_time` `engagement` `first_purchase_time` `geolocation_city` `geolocation_country` `geolocation_state` `geolocation_zip` `largest_purchase_item_price` `last_click` `last_open` `last_pageview` `last_purchase_time` `lifetime_message` `lists` `list_signup` `opens` `optout_time` `pageviews` `profile_created_date` `purchase_count` `purchase_incomplete` `purchase_price` `signup` `top_device` `vars`	Example

export_list_data Examples

Required - list

POST MODE
Type	Parameter
Required For `export_list_data`	`list`
Example
`{ "job":"export_list_data", "list":"MyUsers" }`

Optional - fields

POST MODE
Type	Parameter
Optional For `export_list_data`	`fields`
Example
`{ "job":"export_list_data", "list":"MyUsers", "fields": { "opens":1, "vars": { "userId":1, "user_type":1 } } }`

export_purchase_log

Export user data from a list in CSV format.

Example Call

Copy

{
    "job":"export_purchase_log",
    "start_date":20160101,
    "end_date":20160131
}

Example Response

Copy

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

Type	Parameter	Description	Example
Required for job	`start_date`	Purchase report's start date `start_date` and `end_date`'s format: yyyymmdd. Example: `20150115` The range between `start_date` and `end_date` cannot exceed 31 days	Example
Required for job	`end_date`	Purchase report's end date	Example

export_purchase_log Examples

Required - start_date-end_date

POST MODE
Type	Parameter
Required For `export_purchase_log`	`start_date`, `end_date`
Example
`{ "job":"export_purchase_log", "start_date":20120131, "end_date":20120131 }`

export_scheduled_sends

Download a CSV report of all currently-scheduled transactional sends. No additional parameters are required

import

Emails (Directly)

Copy

{
    "job":"import",
    "list":"List 1",
    "emails":"user1@sailthru.com,user2@sailthru.com,user3@sailthru.com"
}

File (Upload)

Copy

{
    "job":"import",
    "list":"List 1",
    "file":"/tmp/users.txt"
}

URL

Copy

{
    "job":"import",
    "list":"List 1",
    "url":"https://s3.amazonaws.com/sailthru-static/users.csv"
}

Response

Copy

{
    "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). In addition to `list`, you must pass one of the following parameters, but not all three: `emails` `file` `url`	Example
Required for job	`emails`	Emails to upload to the list	Example
Required for job	`file`	File data to upload as a list. Note: This is not a URL! File must be a CSV or text file with one email per line The maximum upload file size is 1 GB	Example
Required for job	`url`	URL to pull data from	Example
Optional for job	`signup_dates`	This parameter is for updating custom signup dates. You must upload a CSV file with the first column titled "email," and the second column titled "signup_date." Pass `1` or `true` to overwrite or set custom signup dates for existing users or new users Date variables cannot be in UNIX. How to set Custom Signup Dates	Example

import Examples

Required list

POST MODE
Type	Parameter
Required For `import`	`list`
Example
`{ "job":"import", "list":"My List" }`

Required emails

POST MODE
Type	Parameter
Required For `import`	`emails`
Example
`{ "job":"import", "list":"My List", "emails": "example1@sailthru.com,example2@sailthru.com,example3@sailthru.com" }`

Required file

POST MODE
Type	Parameter
Required For `import`	`file`
Example
`{ "job":"import", "list":"My List", "file":".../Users/myusername/Documents/myfile.csv" }`

Required url

POST MODE
Type	Parameter
Required For `import`	`url`
Example
`{ "job":"import", "list":"My List", "url":"https://www.example.com/feed/ourfeed" }`

Optional signup_dates

POST MODE
Type	Parameter
Optional For `import`	`signup_dates`
Example
`{ "job":"import", "list":"My List", "url":"https://www.example.com/feed/ourfeed" "signup_dates":1 }`

purchase_import

Example Call

Copy

{
    "job":"purchase_import",
    "file":"/tmp/file.txt"
}

Type	Parameter	Description	Example
Required for job	`file`	UTF-8 text file containing JSON objects. The file must contain one JSON object per line (separated by hard returns, not commas) Each object must match the purchase API POST format, with the following exceptions: date and extid are required the following parameters should not be included, as they only apply to purchases recorded in realtime: message_id, incomplete, reminder_template, send_tempate, reminder_time Max file size is 1 GB 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 `purchase_import` job. If you don't turn off your LO flows, this job could trigger a large number of entries.	Example

purchase_import Examples

Required - file

POST MODE
Type	Parameter
Required For `purchase_import`	`file`
Example
Call JSON `{ "job":"purchase_import", "file":"/tmp/file.txt" }` 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"}]} The following is an easier-viewed but unsupported format. { "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://example.com/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://example.com/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://example.com/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://example.com/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://example.com/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://example.com/stock/black_mens_shoes.jpg" }], "vars": { "order_level_var": "shoes_purchase" }, "adjustments": [{ "price": 2500, "title": "Express Shipping" }] }

Use Cases

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: emailand signup_date. Additionally, the "signup_dates" parameter must be passed in the call with a value of 1or true.

Example in PHP:

Copy

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

Copy

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

Error Codes

Job	HTTP Code	Error Code	Error Message	Notes
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
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

job – Import and Export

Import and Export jobs

How it Works

Universal Job Parameters

GET Mode

POST Mode

export_list_data

Example Min. Parameters

Example with Optional Fields & SHA256 Hashing

export_list_data Examples

Required - list

Optional - fields

export_purchase_log

Example Call

Example Response

export_purchase_log Examples

Required - start_date-end_date

export_scheduled_sends

import

Emails (Directly)

File (Upload)

URL

Response

import Examples

Required list

Required emails

Required file

Required url

Optional signup_dates

purchase_import

Example Call

purchase_import Examples

Required - file

Use Cases

Set Custom Signup Date

Error Codes