Python API client for sendwithus.com
Project description
sendwithus python-client
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 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()
Get a Specific Template
api.get_template(
'YOUR-TEMPLATE-ID'
)
Get a Specific Template Version
api.get_template(
'YOUR-TEMPLATE-ID',
version='YOUR-VERSION-ID'
)
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',
preheader='Optional preheader'
)
Create a New Locale
api.create_new_locale(
'YOUR-TEMPLATE-ID',
locale='fr-FR',
version_name='Version Name',
subject='Email Subject',
html='<html><head></head><body>Valid HTML</body></html>',
text='Optional text content',
preheader='Optional preheader'
)
Create a New Version
api.create_new_version(
template_id='YOUR-TEMPLATE-ID',
name='Version Name',
subject='Email Subject',
html='<html><head></head><body>Valid HTML</body></html>',
text='Optional text content',
preheader='Optional preheader',
locale='fr-FR'
)
Update a Template Version
api.update_template_version(
template_id='YOUR-TEMPLATE-ID',
version_id='YOUR-VERSION-ID',
name='Email Name'
subject='Email Subject',
html='<html><head></head><body>Valid HTML</body></html>',
text='Optional text content',
preheader='Optional preheader'
)
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)
- email_version_name (option) — Template version to send (ie: Version A)
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. 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={
'address': 'company@company.com',
'reply_to':'info@company.com', # Optional
'name': 'Company' # Optional
}
)
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='YOUR-ESP-ID'
)
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='fr-FR'
)
print r.status_code
# 200
Optional Version Name
r = api.send(
email_id='YOUR-TEMPLATE-ID',
recipient={
'name': 'Matt',
'address': 'us@sendwithus.com'
},
email_version_name='Version A'
)
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 &emdash; 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='fr-FR'
)
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'
)
Remove a Customer from a Single Drip Campaigns
api.remove_from_drip_campaign(
'customer@example.com',
'dc_1234asdf1234'
)
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 Locale
You can use the same endpoint to create or update a customer. This is primarily used to associate a locale with an email address so Sendwithus can automatically send them the correct template. Note that if your templates are only in one language then you don't need to use this feature.
api.customer_create(
'customer@example.com',
locale="fr-FR"
)
Delete a Customer
api.customer_delete(
'customer@example.com'
)
Snippets
Get All Snippets
api.snippets()
Get a Specific Snippet
api.get_snippet(
'snp_1234asdf1234'
)
Create a Snippet
api.create_snippet(
name='My Snippet',
body='<h1>Snippets!</h1>'
)
Update a Snippet
api.update_snippet(
'snp_1234asdf1234',
name='My Snippet',
body='<h1>Snippets!</h1>'
)
Internationalization (i18n) API
Get translation package (.pot file)
api.get_translation_template(
`my_translation_tag`
)
Post translated strings and .po files
with open('my_translation_file', 'rb') as f:
api.create_translation_file(
`my_translation_tag`,
f.read()
)
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(
email_id='YOUR-TEMPLATE-ID',
email_data={
'amount': '$12.00'
},
locale='fr-FR',
version_name='French-Version',
strict=False
)
Batch API
Sendwithus' API has a batch endpoint that can take multiple requests and execute them concurrently. Note that Sendwithus recommends keeping batch requests to 10 items or less.
Creating and Executing a Batch Request
api = sendwithus.api('YOUR-API-KEY')
batch = api.start_batch()
emails = [
'user+1@example.com',
'user+2@example.com',
# ...
'user+10@example.com'
]
# Generate the batch request
for email in emails:
batch.send(
email_id='YOUR-TEMPLATE-ID',
recipient={
'address': email
}
)
print batch.command_length() # show number of items in the batch request
results = batch.execute() # returns a `requests` Response Object
Expected Responses
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 &emdash; Successful Request
- 4xx &emdash; Failed Request (Client error)
- 5xx &emdash; 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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for sendwithus-5.3.0-py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 400ff36d88fca50f5509700b7bf92ecafe98894ce4d174afce356ddd357729d9 |
|
| MD5 | 4c4dde3b525ea756493554b636443212 |
|
| BLAKE2b-256 | dd39536412631207525df5f9859ad702a3eb5e163f70e479dfe5b15763e2fe61 |
