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,
   }
}
TypeParameterDescriptionExample
Required for joblistName of the list to exportExample
Optional for jobhash_algoThe 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 jobfieldsThe 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
TypeParameter
Required For export_list_datalist
Example
{
    "job":"export_list_data",
    "list":"MyUsers"}

Optional - fields

POST MODE
TypeParameter
Optional For export_list_datafields
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.

TypeParameterDescriptionExample
Required for jobstart_datePurchase 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 jobend_datePurchase report's end dateExample

export_purchase_log Examples

Required - start_date-end_date

POST MODE
TypeParameter
Required For export_purchase_logstart_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.

TypeParameterDescriptionExample
Required for joblistThe 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 jobemailsEmails to upload to the listExample
Required for jobfileFile 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 joburlURL to pull data fromExample
Optional for jobsignup_datesThis 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
TypeParameter
Required For importlist
Example
{
    "job":"import",
    "list":"My List"}

Required emails

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

Required file

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

Required url

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

Optional signup_dates

POST MODE
TypeParameter
Optional For importsignup_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"}
TypeParameterDescriptionExample
Required for jobfileUTF-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
TypeParameter
Required For purchase_importfile
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

Set Custom Signup Date

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

JobHTTP CodeError CodeError MessageNotes
export_list_data4002Missing required parameter: list
export_list_data40499List not found
export_purchase_log40018Missing required parameter: start_date,end_date
export_purchase_log40018Invalid start_date/end_date fromat
export_purchase_log40018Invalid date range. Start Date canot be later than End Date
export_purchase_log40018Invalid date range. Up to 31 days allowed but {day_range} givenStart_date and end_date too far apart
import4002 Missing required parameter: list
import20099Invalid list name:
import40099One of the following parameters is required: emails, url, or file
import40099Invalid URL
File Import jobs(content_update,purchase_import, import)40099File Parameter is required
File Import jobs(content_update,purchase_import,import)40099The size of the file exceeds the maximum upload file size Max upload is 1gb
File Import jobs(content_update,purchase_import,import)40099Failed to upload file
File Import jobs(content_update,purchase_import,import)40099 Unable to determine the size of the fileMight not be reachable error
File Import jobs(content_update,purchase_import,import)40099File not setMight not be reachable error
40099Invalid JSON provided