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 finishedpostback_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_key and sig, so that the request can be optionally verified as a legitimate Sailthru request)https://api.sailthru.com/job
Fetch status of a job
| Parameter | Description | Example |
|---|---|---|
job_id | Job ID | 4dd58f036803fa3b5500000b |
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 2011 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 2011 13:55:10 -0400 |
For export jobs like: 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".
Request that a job start processing.
| Parameter | Description | Example |
|---|---|---|
job | Type of the job | import |
| 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:
Import a number of email addresses into a list.
| Parameter | Description | Example |
|---|---|---|
list | Name of a list to make import; if list doesn't exist, it will be created | my list |
You must pass one of the below, but not both:
| Parameter | Description | Example |
|---|---|---|
emails | Comma separated emails | john@example.com,praj@sailthru.com |
file | File data (must be POSTed as a file) to upload as a list; CSV or text with one email per line | myfile.csv |
The maximum upload file size for the file parameter is 10 MB for now. Please contact us if this seems unduly restrictive, we will consider customer feedback in possibly raising this limit.
Perform a bulk update of any number of user profiles. You can use this to import a great deal of user data, generate a list for any user matching a query, opt out a large list of email addresses, and many more.
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 query for format |
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 to 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[optout] | blast to opt users out of campaigns only, all to opt users out of all communications, none to opt the user back in |
If you want a campaign to send as soon as the update completes, you can use schedule_blast
| Parameter | Description | |
|---|---|---|
schedule_blast | blast_id of the blast that you want to send upon completion | 234198 |
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:
update parameter)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}}
The update job is very flexible and powerful. See job-update-examples for some examples.
Export user data from a list in CSV format.
| Parameter | Description | Example |
|---|---|---|
list | Name of a list to export | my list |
list | The list name | my list |
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.
Export blast data in CSV format.
| Parameter | Description | Example |
|---|---|---|
blast_id | Valid Blast Id | 190940 |
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.
Query your userbase and generate a detailed snapshot of their analytics similar to that shown in the Snapshot Report in the Sailthru interface.
| Parameter | Description | Example |
|---|---|---|
query | Query – see query for the exact format | query[criteria][0]=domain |
query | Data structure containing the query | |
snapshot | Data structure containing the results of the snapshot |
Query your userbase and generate a detailed snapshot of their analytics similar to that shown in the Snapshot Report in the Sailthru interface.
| 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 |
stats | Data structure containing the results of the snapshot |
(In alpha) Review your available adFlight Advanced inventory over a date range.
| Parameter | Description | Example |
|---|---|---|
start_date | Start of the date range to examine | 20110901 |
end_date | End of the date range to examine | 20111231 |
inventory | Data structure containing available and used inventory by day | |
conflicts | Data structure containing days that represent conflicts under current scheduling |