job

Overview

Start or get the status of a background job, such as a data import or export. Jobs are asynchronous – they may take minutes or hours to run, depending on how large they are. Therefore, the job POST call will return a job_id, which you can use later to request the current status of the job with the GET call.

In addition, there are two other mechanisms you can use to notify you when a job is complete. These are optional parameters for any job call: report_email- an email to receive a short report when the job is finished. postback_url- a URL that will receive a POST with the results of the job (the same data that you would get from a GET call on the job, with two additional parameters: api_keyand sig, so that the request can be optionally verified as a legitimate Sailthru request)

Base URL

https://api.sailthru.com/job

GET Mode

Fetch status of a job

Required

Parameter	Description	Example
`job_id`	Job ID	`4dd58f036803fa3b5500000b`

Return Value

Will return a data structure including some or all of the following information:

Field	Description	Example
`job_id`	Unique Job ID	`4dd58f036803fa3b5500000b`
`status`	completed, pending or error	`pending`
`name`	name of the job	`List Import`
`start_time`	date time when the job was started; this field may not be available if job is not yet started	`Fri, 20 May 2012 13:50:28 -0400`
`end_time`	date time when the job finished; this field will not be available if job is not completed	`Fri, 20 May 2012 13:55:10 -0400`

For export jobs including export_list_data and blast_query, export_url will be returned if the job is completed and it's not expired. If the job is expired, expired field with value true will be returned.

Currently, all export URL of export jobs are removed after approximately 2 hours of creation.

Additional information returned will depend on the type of the job, and is documented below under "Job Types".

POST Mode

Request that a job start processing.

Required Parameters

Parameter	Description	Example
`job`	Type of the job	`import`

Optional Parameters

Parameter	Description	Example
`report_email`	Email to receive a short report when the job is complete	`example@example.com`
`postback_url`	URL to post the results of the job when the job is complete	`http://www.example.com/service/job-result`

Other required and optional parameters depend on the job type, as follows:

Examples

Job Types

ad_inventory

Review your available adFlight Advanced inventory over a date range.

Required Parameters

Parameter	Description	Example
`start_date`	Start of the date range to examine	`20120901`
`end_date`	End of the date range to examine	`20121231`

Return Value

`inventory`	Data structure containing available and used inventory by day
`conflicts`	Data structure containing days that represent conflicts under current scheduling

blast_query

Export campaign data in CSV format

Additional Required Parameters

Parameter	Description	Example
`blast_id`	Valid Blast Id	`190940`

Return Value

`blast_id`	Blast ID	`190940`
`filename`	The filename generated	`my-list.csv`
`export_url`	A URL pointing to the exported data. The data will be removed after 24 hours.	`http://s3.amazonaws.com/sailthru/path/to/export`

The export URL will contain PII hashed data.

blast_save_list

Query your userbase who received a specific campaign and save that new segment to a new or existing list.

Parameter	Description	Example
blast_id	ID of the blast you wish to take a snapshot of	123456
query	Query – see query for the exact format	query[criteria][0]=domain
list	name of the list to add users to (if it doesn't exist, it will be created)	Opened-Jun-15-Campaign

Optional Parameters

Parameter	Description	Example
`report_email`	Receive an email notification when this job has completed.	"report_email":"me@mydomain.com"

Please see examples here.

blast_snapshot

Query your userbase who received a specific campaign and generate a detailed snapshot of their analytics (similar to the Snapshot Report in the Sailthru interface).

Required Parameters

Parameter	Description	Example
`query`	Query – see query for the exact format	`query[criteria][0]=domain`
`blast_id`	id of the blast you wish to take a snapshot of

Return Value

stats Data structure containing the results of the snapshot

export_list_data

Export user data from a list in CSV format

Additional Required Parameters

Parameter	Description	Example
`list`	Name of the list to export	`my list`

Optional Parameters

Parameter	Description	Example
`fields`	The field or fields of data to export.	"fields":{"lists":1,"vars":{varname:1}}

The export URL will contain PII hashed data.

export_scheduled_sends

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

import

Import a number of email addresses into a list

Required Parameters

Parameter	Description	Example
`list`	Name of a list to make import; if list doesn't exist, it will be created	`my list`

Additional Required Parameters

You must pass one of the below, but not both:

Parameter	Description	Example
`emails`	Comma separated emails	`john@example.com,joe@example.com`
`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.	`/Users/myusername/Documents/myfile.csv`

Max upload file size for file parameter is 10 MB for now. Please contact Support if this seems restrictive, as we will consider customer feedback in possibly raising this limit.

snapshot

Query your userbase and generate a detailed snapshot of their analytics similar to that shown in the Snapshot Report in the Sailthru interface.

Required Parameters

Parameter	Description	Example
`query`	Query – see query for the exact format	`{"job":"snapshot","report_email":"myname@mydomain.com","query":{"source_list":"Main","query_mode":"and","criteria":["domain"],"value":["gmail.com"]}}`

Return Value On Completion

`query`	Data structure containing the query
`snapshot`	Data structure containing the results of the snapshot

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.

Required Parameters

You must pass one of the below, but not more than one. The below determines the users to operate on.

Parameter	Description	Example
`emails`	Comma separated list of emails to perform the update on	`john@example.com,ian@sailthru.com`
`url`	URL to pull data from – see file format below	`http://www.example.com/feed/ourfeed`
`file`	File data to upload – see file format below
`query`	Query – see queries for format

Optional Parameter: update

If you want to apply the same update to all of the users specified, you should pass the update parameter. The possible values of the update parameter are similar to that of the POST parameters of the email API call.

Parameter	Description
`update[vars]`	key/value hash of vars to set
`update[lists]`	key/value hash of lists to subscribe or unsubscribe to, where `1`means subscribe and `0`means unsubscribe
`update[schedule_blast]`	will automatically schedule the blast to send the moment the update completes
`update[optout]`	`blast`to opt users out of campaigns only, `all`to opt users out of all communications, `none`to opt the user back in

Data File Format

If you are using the url or file format, then you are pulling from a file or URL. This can be one of two formats:

Simple format: email address per line. In this case you are just specifying a list of users to perform the same updates on (as specified by the update parameter)
JSON format: JSON object per line. This lets you specify individual updates on a per-user basis. Each line should contain a JSON object containing an email element to identify the user, and optionally vars, lists, or optout as described above.

{"email":"ian@sailthru.com","vars":{"name":"Ian White","company":"Sailthru"},"lists":{"Sailthru Employees":1}}
{"email":"praj@sailthru.com","vars":{"name":"Prajwal Tuladhar","company":"Sailthru"},"lists":{"Sailthru Employees":1}}
{"email":"john@example.com","vars":{"name":"John Doe","company":"Anycorp"},"lists":{"Sailthru Customers":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}})

Examples

See Job Update Examples for samples.