Giters

infinit / sendwithus_python

Sendwithus Python Client

Home Page:https://www.sendwithus.com

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

sendwithus python-client

Build Status

Requirements

Installation

pip install sendwithus

Usage

For all examples, assume:

import sendwithus
api = sendwithus.api(api_key='YOUR-API-KEY')

Error Handling

By default, the API calls return a response object. However, you can use sendwithus.api(api_key='YOUR-API-KEY', raise_errors=True) which will raise the following errors:

  • AuthenticationError - Caused by an invalid API key
  • APIError - Caused by an invalid API request (4xx error)
  • ServerError - Caused by a server error (5xx error)

Errors can be imported from the sendwithus.exceptions module.

Templates

Get your Templates

api.templates()

Create a Template

api.create_template(
    name='Email Name',
    subject='Email Subject',
    html='<html><head></head><body>Valid HTML</body></html>',
    text='Optional text content')

We validate all HTML and will return an error if it's invalid.

r.status_code
# 400
r.content
# 'email html failed to validate'

Send

NOTE - If a customer does not exist by the specified email (recipient address), the send call will create a customer.

  • email_id — Template ID to send
  • recipient
    • address — The recipient's email address
    • name (optional) — The recipient's name
  • email_data (optional) — Object containing email template data
  • sender (optional)
    • address — The sender's email address
    • reply_to — The sender's reply-to address
    • name — The sender's name
  • cc (optional) — A list of CC recipients, of the format {"address":"cc@email.com"}
  • bcc (optional) — A list of BCC recipients, of the format {"address":"bcc@email.com"}
  • headers (options) — Object contain SMTP headers to be included with the email
  • esp_account (optional) — ID of the ESP Account to send this email through. ex: esp_1a2b3c4d5e
  • files (optional) — List of file attachments (combined maximum 7MB)
  • inline (optional) — Inline attachment object
  • locale (optional) — Template locale to send (ie: en-US)

Call with REQUIRED parameters only

The email_data field is optional, but highly recommended!

r = api.send(
    email_id='YOUR-TEMPLATE-ID',
    recipient={'address': 'us@sendwithus.com'})
print r.status_code
# 200

Call with REQUIRED parameters and email_data

r = api.send(
    email_id='YOUR-TEMPLATE-ID',
    recipient={'address': 'us@sendwithus.com'},
    email_data={ 'first_name': 'Matt' })
print r.status_code
# 200

Optional Sender

The sender['address'] is a required sender field

r = api.send(
    email_id='YOUR-TEMPLATE-ID',
    recipient={ 'name': 'Matt',
                'address': 'us@sendwithus.com'},
    email_data={ 'first_name': 'Matt' },
    sender={ 'address':'company@company.com' })
print r.status_code
# 200

Optional Sender with reply_to address

sender['name'] and sender['reply_to'] are both optional

r = api.send(
    email_id='YOUR-TEMPLATE-ID',
    recipient={ 'name': 'Matt',
                'address': 'us@sendwithus.com'},
    email_data={ 'first_name': 'Matt' },
    sender={ 'name': 'Company',
                'address':'company@company.com',
                'reply_to':'info@company.com'})
print r.status_code
# 200

Optional CC

r = api.send(
    email_id='YOUR-TEMPLATE-ID',
    recipient={'name': 'Matt',
                'address': 'us@sendwithus.com'},
    cc=[
        {'address': 'company@company.com'},
        {'address': 'info@company.com'}
    ])
print r.status_code
# 200

Optional BCC

r = api.send(
    email_id='YOUR-TEMPLATE-ID',
    recipient={'name': 'Matt',
                'address': 'us@sendwithus.com'},
    bcc=[
        {'address': 'company@company.com'},
        {'address': 'info@company.com'}
    ])
print r.status_code
# 200

Optional Headers

r = api.send(
    email_id='YOUR-TEMPLATE-ID',
    recipient={'name': 'Matt',
                'address': 'us@sendwithus.com'},
    headers={'X-HEADER-ONE': 'header-value'})
print r.status_code
# 200

Optional ESP Account

r = api.send(
    email_id='YOUR-TEMPLATE-ID',
    recipient={'name': 'Matt',
                'address': 'us@sendwithus.com'},
    esp_account='esp_1234asdf1234')
print r.status_code
# 200

Optional File Attachments

r = api.send(
    email_id='YOUR-TEMPLATE-ID',
    recipient={'name': 'Matt',
               'address': 'us@sendwithus.com'},
    files=[open('/home/Matt/report1.txt', 'r'), open('/home/Matt/report2.txt', 'r')])
print r.status_code
# 200

Optional File Attachments with explicit file names

r = api.send(
    email_id='YOUR-TEMPLATE-ID',
    recipient={'name': 'Matt',
               'address': 'us@sendwithus.com'},
    files=[{'file': open('/home/Matt/report1.txt', 'r'),
            'filename': 'arbitrary_file_name.xyz'}])
print r.status_code
# 200

Optional Inline Image

r = api.send(
    email_id='YOUR-TEMPLATE-ID',
    recipient={'name': 'Matt',
               'address': 'us@sendwithus.com'},
    inline=open('image.jpg', 'r'))
print r.status_code
# 200

Optional Inline Image with explicit file names

r = api.send(
    email_id='YOUR-TEMPLATE-ID',
    recipient={'name': 'Matt',
               'address': 'us@sendwithus.com'},
    inline={'file': open('/home/Matt/image.jpg, 'r'),
            'filename': 'cool_image.jpg'})
print r.status_code
# 200

Optional Locale

r = api.send(
    email_id='YOUR-TEMPLATE-ID',
    recipient={'name': 'Matt',
               'address': 'us@sendwithus.com'},
    locale='en-US')
print r.status_code
# 200

Drip Campaigns

List all Drip Campaigns

List all drip campaigns for the current profile

api.list_drip_campaigns()

Start a Customer on a Drip Campaign

Starts a customer on the first step of a specified drip campaign

api.start_on_drip_campaign('dc_1234asdf1234', {'address':'customer@email.com'})

Start a Customer on a Drip Campaign with email_data

You may specify extra data to be merged into the templates in the drip campaign.

Note — Any data provided in the email_data parameter for start_on_drip_campaign() will be used throughout the entire drip campaign.

api.start_on_drip_campaign(
    'dc_1234asdf1234',
    {'address':'customer@email.com'},
    email_data={'color': 'blue'},
    sender={'address': 'from@email.com'},
    cc=[{'address': 'cc@email.com'}],
    tags=['tag_one', 'tag_two'],
    esp_account='esp_1234',
    locale='en-US'
)

Remove a Customer from a Drip Campaign

Deactivates all pending emails for a customer on a specified drip campaign

api.remove_from_drip_campaign('customer@email.com', 'dc_1234asdf1234')

Remove a Customer from all Drip Campaigns

You can deactivate all pending drip campaign emails for a customer

api.drip_deactivate('customer@example.com')

List the details of a specific Drip Campaign

api.drip_campaign_details('dc_1234asdf1234')

Customers

Get a Customer

api.customer_details('customer@example.com')

Create/Update Customer

You can use the same endpoint to create or update a customer. Sendwithus will perform a merge of the data on the customer profile, preferring the new data.

api.customer_create('customer@example.com', data={'first_name': 'Matt'})

Delete a Customer

api.customer_delete('customer@example.com')

Render

Render a Template with data

The Render API allows you to render a template with data, using the exact same rendering workflow that Sendwithus uses when delivering your email. Strict is set to False as a default, if Strict=True this API call will fail on any missing email_data.

api.render('tem_12345', { "amount": "$12.00" }, locale='fr-FR', version_name='French-Version', strict=False)

Expected Response

Success

    >>> r.status_code
    200

    >>> r.json().get('success')
    True

    >>> r.json().get('status')
    u'OK'

    >>> r.json().get('receipt_id')
    u'numeric-receipt-id'

Error cases

  • malformed request
    >>> r.status_code
    400
  • bad API key
    >>> r.status_code
    403

Run Tests

Use tox to run the tests:

tox

Testing Multiple Python Versions

This assumes you have tox installed and used pyenv to install multiple versions of python.

Once all the supported python versions are installed simply run:

tox

This will run the tests against all the versions specified in tox.ini.

Troubleshooting

General Troubleshooting

  • Enable debug mode
  • Make sure you're using the latest Python client
  • Capture the response data and check your logs — often this will have the exact error

Enable Debug Mode

Debug mode prints out the underlying request information as well as the data payload that gets sent to Sendwithus. You will most likely find this information in your logs. To enable it, simply put DEBUG=True as a parameter when instantiating the API object. Use the debug mode to compare the data payload getting sent to Sendwithus' API docs.

import sendwithus
api = sendwithus.api(api_key='YOUR-API-KEY', DEBUG=True)

Response Ranges

Sendwithus' API typically sends responses back in these ranges:

  • 2xx – Successful Request
  • 4xx – Failed Request (Client error)
  • 5xx – Failed Request (Server error)

If you're receiving an error in the 400 response range follow these steps:

  • Double check the data and ID's getting passed to Sendwithus
  • Ensure your API key is correct
  • Log and check the body of the response

Internal

To package

  python setup.py sdist bdist_wheel upload

About

Sendwithus Python Client

https://www.sendwithus.com

License:Apache License 2.0

Languages

Language:Python 100.0%