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:

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 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 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 an 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_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

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