Sailthru’s Python client library can be found on Github and PyPi, and supports Python 2.6, Python 2.7, and 3.3+.



pip install sailthru-client

If running Python 2.x, make sure that the simplejson library is compiled so that responses from the client are Python strings instead of unicode strings. If a response has a unicode string (example: a list name is written with characters that do not exist in ASCII), it will automatically come back as a Python unicode string. If simplejson is not compiled, all keys and values will be unicode strings, which may cause issues when interfacing with other libraries.

In Python 3, every response is a str object, which is by default a unicode string. Since responses are from JSON strings, they should be encoded as ‘utf-8′.

Running Tests

Clone the sailthru-python-client repository and then run the following commands :

pip install -r requirements.txt


from sailthru.sailthru_client import SailthruClient

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

The client provides convenience functions for many of the endpoints we provide, however, the following examples demonstrate using the client via the bare interface.

POST & GET user API Endpoint

response = sc.api_post('user', {'id': '', 'lists': {'New Subscribers List': 1}, 'vars': {'name': 'John Doe', 'zip_code': '09123', 'birthdate': '02/29/1956'}})
if response.is_ok():
print response.get_body()
print response.get_error()

Executing GET Request

request_data = {'id': ''}
response = sailthru_client.api_get('user', request_data).get_body()

DELETE template API Endpoint

request_data = {'template': 'My-unused template'}
response = sailthru_client.api_delete('template', request_data).get_body()

GET list Call

# returns JSON string of all lists
print sc.get_lists()

# returns a single list
list_name = 'mylistname'
print sc.api_get('list', {"list": list_name}).get_body()

API Postbacks

# for authenticating verify postbacks
verify_params = {'action': 'verify', 'email': '', 'send_id': 'TE8EZ3-LmosnAgAA', 'sig': 'generated_signature'}
is_verified_postback = sailtrhu_client.recieve_verify_post(verify_params)
# for authenticating optout postbacks
optout_params = {'action': 'verify', 'email': '', 'sig': 'generated_signature'}
is_optout_postback = sailtrhu_client.recieve_optout_post(optout__params)
# for authenticating hardbounce postbacks
hardbounce_params = {'action': 'hardbounce', 'email': '', 'sig': 'generated_signature'}
is_hardbounce_postback = sailtrhu_client.recieve_hardbounce_post(hardbounce_params)

Multipart Requests (Sending Files)

# Import Job API Call
response = sailthru_client.api_post("job", {"job": "import", "file": "/tmp/my_file", "list": "Python-List"}, ['file'])

Rate Limits

rate_limit_info = sailthru_client.get_last_rate_limit_info('user', 'POST')

# get_last_rate_limit_info returns None if given endpoint/method wasn't triggered previously
if rate_limit_info is not None:
    limit = rate_limit_info['limit'];
    remaining = rate_limit_info['remaining'];
    reset_timestamp = rate_limit_info['reset'];

    # throttle api calls based on last rate limit info
    if remaining <= 0:
         seconds_till_reset = reset_timestamp - time.time()
         # sleep or perform other business logic before next user api call