sendwithus python-client
requirements
python requests library
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 keyAPIError- 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 -- 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":"[email protected]"}
- bcc (optional) -- A list of BCC recipients, of the format {"address":"[email protected]"}
- 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-EMAIL-ID',
recipient={'address': '[email protected]'})
print r.status_code
# 200Call with REQUIRED parameters and email_data
r = api.send(
email_id='YOUR-EMAIL-ID',
recipient={'address': '[email protected]'},
email_data={ 'first_name': 'Matt' })
print r.status_code
# 200Optional Sender
The sender['address'] is a required sender field
r = api.send(
email_id='YOUR-EMAIL-ID',
recipient={ 'name': 'Matt',
'address': '[email protected]'},
email_data={ 'first_name': 'Matt' },
sender={ 'address':'[email protected]' })
print r.status_code
# 200Optional Sender with reply_to address
sender['name'] and sender['reply_to'] are both optional
r = api.send(
email_id='YOUR-EMAIL-ID',
recipient={ 'name': 'Matt',
'address': '[email protected]'},
email_data={ 'first_name': 'Matt' },
sender={ 'name': 'Company',
'address':'[email protected]',
'reply_to':'[email protected]'})
print r.status_code
# 200Optional CC
r = api.send(
email_id='YOUR-EMAIL-ID',
recipient={'name': 'Matt',
'address': '[email protected]'},
cc=[
{'address': '[email protected]'},
{'address': '[email protected]'}
])
print r.status_code
# 200Optional BCC
r = api.send(
email_id='YOUR-EMAIL-ID',
recipient={'name': 'Matt',
'address': '[email protected]'},
bcc=[
{'address': '[email protected]'},
{'address': '[email protected]'}
])
print r.status_code
# 200Optional Headers
r = api.send(
email_id='YOUR-EMAIL-ID',
recipient={'name': 'Matt',
'address': '[email protected]'},
headers={'X-HEADER-ONE': 'header-value'})
print r.status_code
# 200Optional ESP Account
r = api.send(
email_id='YOUR-EMAIL-ID',
recipient={'name': 'Matt',
'address': '[email protected]'},
esp_account='esp_1234asdf1234')
print r.status_code
# 200Optional File Attachments
r = api.send(
email_id='YOUR-EMAIL-ID',
recipient={'name': 'Matt',
'address': '[email protected]'},
files=[open('/home/Matt/report1.txt', 'r'), open('/home/Matt/report2.txt', 'r')])
print r.status_code
# 200Optional Inline Image
r = api.send(
email_id='YOUR-EMAIL-ID',
recipient={'name': 'Matt',
'address': '[email protected]'},
inline=open('image.jpg', 'r'))
print r.status_code
# 200Optional Locale
r = api.send(
email_id='YOUR-EMAIL-ID',
recipient={'name': 'Matt',
'address': '[email protected]'},
locale='en-US')
print r.status_code
# 200Drip 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':'[email protected]'})Extra Data
You may specify extra data to be merged into the templates in the drip campaign
api.start_on_drip_campaign(
'dc_1234asdf1234',
{'address':'[email protected]'},
email_data={'color': 'blue'},
sender={'address': '[email protected]'},
cc=[{'address': '[email protected]'}],
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('[email protected]', 'dc_1234asdf1234')Remove a customer from all drip campaigns
You can deactivate all pending drip campaign emails for a customer
api.drip_deactivate('[email protected]')List the details of a specific campaign
api.drip_campaign_details('dc_1234asdf1234')Customers
Get a Customer
api.customer_details('[email protected]')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('[email protected]', data={'first_name': 'Matt'})Delete a Customer
api.customer_delete('[email protected]')Add Customer to a Group
api.add_customer_to_group('[email protected]', 'grp_1234')Remove Customer from a Group
api.remove_customer_from_group('[email protected]', 'grp_1234')Conversions
Create a customer conversion event
You can use the Conversion API to track conversion and revenue data events against your sent emails.
NOTE: Revenue is in cents (eg. $100.50 = 10050)
api.customer_conversion('[email protected]', revenue=10050)Customer Groups
Create a Customer Group
api.create_customer_group('group_name', 'sample group description')Delete a customer group
api.delete_customer_group('grp_1234')Update a Customer Group
api.update_customer_group('new_name', 'updated group description')Segmentation
Send Template to Segment
You can use the Segments API to send a template to all customers who match a
segment. The Segment must be created in the Sendwithus dashboard, which is
where you will find the segment_id for use in this API.
api.send_segment('tem_12345', 'seg_1245')Extra Data
You may specify extra data to be merged into the template, alongside the individual customer profiles
api.send_segment('tem_12345', 'seg_12345', email_data={'color': 'blue'})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.
api.render('tem_12345', { "amount": "$12.00" }, '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
to run tests
python setup.py test
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.
packaging (internal)
python setup.py sdist upload
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent