Python Library


A client library for accessing the REST API. It can be installed using pip or downloaded from Github. Supports Python 2.6, Python 2.7, and 3.3+.

Installation:

Copy 
pip install sailthru-client


Running Tests for the python client library: (Additional setup optional) Clone the sailthru-python-client repository and then run the following commands :

Copy 
pip install -r requirements.txt
tox

Defining the client object:

Copy 
from sailthru.sailthru_client import SailthruClient

api_key = '*******'api_secret = '*******'sc = sailthru_client = SailthruClient(api_key, api_secret)

Here, "sc" is the client object and can be used to make low level api calls for GET, POST or DELETE or any of the helper functions.

Low-Level Functions

You can use the following formats to produce GET, POST, or DELETE calls for any API endpoint.

GET

Copy
sc.api_get(<endpoint>, <json_data>)

POST

Copy
sc.api_post(<endpoint>, <json_data>, binary_data_param)

sc.api_post_multipart(<endpoint>, <json_data>, [binary_data_params])

DELETE

Copy
sc.api_delete(<endpoint>, <json_data>)


<endpoint> is an API endpoint. <json_data> is the data required to pass to the endpoint in a python dictionary format.p

Examples:

POST a template

Copy
response = sc.api_post('template', {'template':'test template'})
if response.is_ok():
    print response.get_body()
else:
    print "Error Code " + str(response.get_error().get_error_code())
    print response.get_error().get_message()
**POST a update job for updating signup_date of users reading from a file (example of using ****Binary_data_param****)**

filepath = "/Users/sudiptamohapatra/Documents/signup_test.csv"response = sc.api_post("job",{"job":"update", "file":filepath, "update":{"signup_date":"20150522", "vars":{"num":8}}}, {"file":filepath})
if response.is_ok():
    print response.get_body()
else:
    print "Error Code " + str(response.get_error().get_error_code())
    print response.get_error().get_message()

GET a user

Copy
response = sc.api_get('user', {'id':'sailthruuser@test.com'})
if response.is_ok():
    print response.get_body()
else:
    print "Error Code " + str(response.get_error().get_error_code())
    print response.get_error().get_message()

DELETE a template

Copy
response = sc.api_delete('template', {'template':'test template'})
if response.is_ok():
    print response.get_body()
else:
    print "Error Code " + str(response.get_error().get_error_code())
    print response.get_error().get_message()

Not all endpoints support http delete calls.

Helper Functions

The library contains helper functions for most endpoint/method combinations (i.e. GET/POST/DELETE for each API endpoint). They generally return a JsonResponse object-which is just a wrapper around the API's JSON response-and an OK boolean status. Many of these functions accept POJO parameters, as defined in the library--e.g. Blast, User, Template. These objects are to be constructed before invoking the API method. Their various fields are set by chaining their builder-style setter methods.

Send

  • send(template, email, _vars=None, options=None, schedule_time=None)
    • Remotely send an email template to a single email address.

    • Takes a String template name

    • email: String Email value

    • _vars : array of key/value vars

    • options: optional dictionary to include replyto and/or test keys

    • schedule_time : do not send the email immediately, but at some point in the future.

  • multi_send(template, emails, _vars=None, evars=None, options=None)

    • Remotely send an email template to multiple email addresses.

  • Takes a String template name

  • emails: List with email values or comma separated email string

  • _vars : array of key/value vars

  • options: optional dictionary to include replyto and/or test keys

  • schedule_time : do not send the email immediately, but at some point in the future.

  • get_send(string send_id)

    • Get the status of a send

  • Takes a send id as an input param

  • cancel_send(string send_id)

    • Cancels an email that you had previously scheduled for future sending with the schedule_time parameter. It is not possible to cancel an email that has not been scheduled.

Blast

  • schedule_blast(name, list, schedule_time, from_name, from_email, subject, content_html, content_text, options=None)
    • Schedule a mass mail blast

    • name: String name to give to this new blast

    • list: mailing list name to send to

    • schedule_time: when the blast should send. Dates in the past will be scheduled for immediate delivery. Any English textual datetime format known to PHP's strtotime function is acceptable, such as 2009-03-18 23:57:22 UTC, now (immediate delivery), +3 hours (3 hours from now), or February 14, 9:30 EST. Be sure to specify a timezone if you use an exact time.

    • from_name: name appearing in the "From" of the email

    • from_email: email address to use as the "from" - choose from any of your verified emails

    • subject: subject line of the email

    • content_html: HTML format version of the email

    • content_text: Text format version of the email

    • options: optional parameters dictionary

      • Blast_id, copy_blast, copy_template, replyto, report_email, is_link_tracking, is_google_analytics, is_public, suppress_list, test_vars, email_hour_range, abtest, test_percent, data_feed_url
  • schedule_blast_from_template(template, list_name, schedule_time, options=None)
    • Schedule a mass mail blast from template

    • template: String template to copy from

    • list_name: list to send to

    • schedule_time

    • options: additional optional params

  • schedule_blast_from_blast(blast_id, schedule_time, options=None)

    • Schedule a mass mail blast from previous blast

  • blast_id: blast_id to copy from

  • schedule_time

  • options: additional optional params

  • update_blast(blast_id, name=None, list=None, schedule_time=None, from_name=None, from_email=None,subject=None, content_html=None, content_text=None, options=None)

    • updates existing blast

  • blast_id: blast id to be updated

  • name: String name of the blast

  • list: blast list

  • schedule_time: new schedule time

  • from_name: name appearing in the "From" of the email

  • from_email: email address to use as the "from" - choose from any of your verified emails

  • subject: subject line of the email

  • content_html: HTML format version of the email

  • content_text: Text format version of the email

  • options: optional parameters dictionary

  • get_blast(blast_id)

    • Gets a blast using a given blast_id
  • delete_blast(blast_id)
    • deletes a blast using a given blast_id
  • cancel_blast(blast_id)
    • cancels a scheduled blast using a given blast_id

Template

  • get_template(template_name)
    • get information of a given template using String template_name
  • get_templates()
    • get metadata for all user templates
  • delete_template(template_name)
    • delete existing template using String template_name
  • save_template(template, template_fields=None)
    • Updates a template based on the fields passed in

    • template: String template_name

    • Template_fields: dictionary of key/value pair of any fields under the template object that needs to be saved or updated.

User

  • get_user(idvalue, options=None)

    • get user by a given id
  • save_user(idvalue, options=None)
    • save user by a given id

List

  • get_list(list_name, options=None)
    • Get detailed metadata information about a list based on a list name
  • get_lists()
    • Get metadata for all lists
  • save_list(list_name, emails)
    • list: list name

    • emails: List of email values or comma separated string

  • delete_list(list_name)

    • delete given list based on the name

Content

  • push_content(title, url, images=None, date=None, expire_date=None, description=None, location=None, price=None, tags=None, author=None, site_name=None, spider=None, vars=None)
    • Push a new piece of content. Expected names for the images argument's map are "full" and "thumb". Expected format for location should be [longitude,latitude]

    • title: title string for the content

    • url: URL string for the content

    • images: map of image names

    • date: date string

    • expire_date: date string for when the content expires

    • description: description for the content

    • location: location of the content

    • price: price for the content

    • tags: list or comma separated string values

    • author: author for the content

    • site_name: site name for the content

    • spider: truthy value to force re-spidering content

    • vars: replaceable vars dictionary

Purchase

  • purchase(email, items=None, incomplete=None, message_id=None, options=None, extid=None)

    • Record that a user has made a purchase, or has added items to their purchase total. http://docs.sailthru.com/api/purchase

  • email: Email string

  • items: list of item dictionary with keys: id, title, price, qty, and url

  • message_id: message_id string

  • extid: external ID to track purchases

  • options: other options that can be set as per the API documentation

  • get_purchase(purchase_id, purchase_key='sid')

    • Retrieve information about a purchase using the system's unique ID or a client's ID

  • purchase_id: a string that represents a unique_id or an extid.

  • purchase_key: a string that is either 'sid' or 'extid', which is 'sid' by default

Stats

  • stats_list(list=None, date=None)

    • Retrieve information about your subscriber counts on a particular list, on a particular day.
  • stats_blast(blast_id=None, start_date=None, end_date=None, options=None)
    • Retrieve information about a particular blast or aggregated information from all of blasts over a specified date range.
  • _stats(data)
    • Makes a Stats API GET request based on the data passed

Postback

  • receive_verify_post(post_params)

  • receive_optout_post(post_params)my.

  • receive_hardbounce_post(post_params)

  • check_for_valid_postback_actions(required_keys, post_params)

Rate Limits

  • get_last_rate_limit_info(action, method)

    • Get rate limit information for last API call

    • action: API endpoint

    • method: Http method, GET, POST or DELETE

    • return: dict|None