A client library for accessing the Sailthru REST API.

It can be installed using pip or downloaded from Github.

Supports Python 2.6, Python 2.7, and 3.3+.

Installation:

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 :

pip install -r requirements.txt
tox

Defining the Sailthru client object:

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 Sailthru API endpoint.

GET

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

POST

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

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

DELETE

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

<endpoint> is a Sailthru API endpoint.

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

Examples:

POST a template

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

response = sc.api_post('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

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()

Note: 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 to Sailthru. 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)

  • https://getstarted.sailthru.com/new-for-developers-overview/api/api-technical-details/#Rate_Limiting

  • Get rate limit information for last API call

  • action: API endpoint

  • method: Http method, GET, POST or DELETE

  • return: dict|None