Skip to content

sendwithus/sendwithus_python

BranchesTags

Repository files navigation

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()

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': '[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)
  • 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': '[email protected]'
    }
)
print r.status_code
# 200

Call with REQUIRED parameters and email_data

r = api.send(
    email_id='YOUR-TEMPLATE-ID',
    recipient={
        'address': '[email protected]'
    },
    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': '[email protected]'
    },
    email_data={
        'first_name': 'Matt'
    },
    sender={
        'address': '[email protected]',
        'reply_to':'[email protected]',  # Optional
        'name': 'Company'  # Optional
    }
)
print r.status_code
# 200

Optional CC

r = api.send(
    email_id='YOUR-TEMPLATE-ID',
    recipient={
        'name': 'Matt',
        'address': '[email protected]'
    },
    cc=[
        {'address': '[email protected]'},
        {'address': '[email protected]'}
    ]
)
print r.status_code
# 200

Optional BCC

r = api.send(
    email_id='YOUR-TEMPLATE-ID',
    recipient={
        'name': 'Matt',
        'address': '[email protected]'
    },
    bcc=[
        {'address': '[email protected]'},
        {'address': '[email protected]'}
    ]
)
print r.status_code
# 200

Optional Headers

r = api.send(
    email_id='YOUR-TEMPLATE-ID',
    recipient={
        'name': 'Matt',
        'address': '[email protected]'
    },
    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': '[email protected]'
    },
    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': '[email protected]'
    },
    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': '[email protected]'
    },
    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': '[email protected]'
    },
    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': '[email protected]'
    },
    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': '[email protected]'
    },
    locale='fr-FR'
)
print r.status_code
# 200

Optional Version Name

r = api.send(
    email_id='YOUR-TEMPLATE-ID',
    recipient={
        'name': 'Matt',
        'address': '[email protected]'
    },
    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': '[email protected]'}
)

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': '[email protected]'},
    email_data={'color': 'blue'},
    sender={'address': '[email protected]'},
    cc=[{'address': '[email protected]'}],
    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(
    '[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]'
)

Remove a Customer from a Single Drip Campaigns

api.remove_from_drip_campaign(
    '[email protected]',
    'dc_1234asdf1234'
)

List the details of a specific Drip Campaign

api.drip_campaign_details(
    'dc_1234asdf1234'
)

Customers

Get a Customer

api.customer_details(
    '[email protected]'
)

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(
    '[email protected]',
    locale="fr-FR"
)

Delete a Customer

api.customer_delete(
    '[email protected]'
)

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 = [
    '[email protected]',
    '[email protected]',
    # ...
    '[email protected]'
]

# 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

About

Sendwithus Python Client

www.sendwithus.com

Resources

Readme

License

Apache-2.0 license
Activity
Custom properties

Stars

31 stars

Watchers

26 watching

Forks

23 forks
Report repository

Releases 11

v5.3.0 Latest
Mar 9, 2023
+ 10 releases

Packages

No packages published

Contributors 26
+ 12 contributors

Languages