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/<span style="color: #333399;">job</span>

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

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

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

{
    "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).
  • 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
  • job Examples
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

{
    "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"}]}
Click here to view the same content in 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:
$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")

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  

Contact us

Top