{ "info": { "author": "sendwithus", "author_email": "us@sendwithus.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 5 - Production/Stable", "License :: OSI Approved :: Apache Software License", "Programming Language :: Python :: 2", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.4", "Programming Language :: Python :: 3.5", "Topic :: Communications :: Email" ], "description": "sendwithus python-client\n========================\n\n[](https://travis-ci.org/sendwithus/sendwithus_python)\n\n## Requirements\n- [Python requests library](http://docs.python-requests.org/en/master/user/install/#install)\n\n## Installation\n pip install sendwithus\n\n## Usage\n\nFor all examples, assume:\n```python\nimport sendwithus\napi = sendwithus.api(api_key='YOUR-API-KEY')\n```\n\n### Error Handling\nBy default, the API calls return a response object. However, you can use\n`sendwithus.api(api_key='YOUR-API-KEY', raise_errors=True)` which will raise the following errors:\n* `AuthenticationError` - Caused by an invalid API key\n* `APIError` - Caused by an invalid API request (4xx error)\n* `ServerError` - Caused by a server error (5xx error)\n\nErrors can be imported from the `sendwithus.exceptions` module.\n\n# Templates\n\n### Get Your Templates\n\n```python\napi.templates()\n```\n\n### Get a Specific Template\n\n```python\napi.get_template(\n 'YOUR-TEMPLATE-ID'\n)\n```\n\n### Get a Specific Template Version\n\n```python\napi.get_template(\n 'YOUR-TEMPLATE-ID',\n version='YOUR-VERSION-ID'\n)\n```\n\n### Create a Template\n\n```python\napi.create_template(\n name='Email Name',\n subject='Email Subject',\n html='
Valid HTML',\n text='Optional text content'\n)\n```\n\n### Create a New Locale\n\n```python\napi.create_new_locale(\n 'YOUR-TEMPLATE-ID',\n locale='fr-FR',\n version_name='Version Name',\n subject='Email Subject',\n html='Valid HTML',\n text='Optional text content'\n)\n```\n\n### Create a New Version\n\n```python\napi.create_new_version(\n template_id='YOUR-TEMPLATE-ID',\n name='Version Name',\n subject='Email Subject',\n html='Valid HTML',\n text='Optional text content',\n locale='fr-FR'\n)\n```\n\n### Update a Template Version\n\n```python\napi.update_template_version(\n template_id='YOUR-TEMPLATE-ID',\n version_id='YOUR-VERSION-ID',\n name='Email Name'\n subject='Email Subject',\n html='Valid HTML',\n text='Optional text content'\n)\n```\n\nWe validate all HTML and will return an error if it's invalid.\n\n```python\nr.status_code\n# 400\nr.content\n# 'email html failed to validate'\n```\n\n# Send\n\n*NOTE* - If a customer does not exist by the specified email (recipient address), the send call will create a customer.\n\n- email_id — Template ID to send\n- recipient\n - address — The recipient's email address\n - name (optional) — The recipient's name\n- email_data (optional) — Object containing email template data\n- sender (optional)\n - address — The sender's email address\n - reply_to — The sender's reply-to address\n - name — The sender's name\n- cc (optional) — A list of CC recipients, of the format {'address': 'cc@email.com'}\n- bcc (optional) — A list of BCC recipients, of the format {'address': 'bcc@email.com'}\n- headers (options) — Object contain SMTP headers to be included with the email\n- esp\\_account (optional) — ID of the ESP Account to send this email through. ex: esp\\_1a2b3c4d5e\n- files (optional) — List of file attachments (combined maximum 7MB)\n- inline (optional) — Inline attachment object\n- locale (optional) — Template locale to send (ie: en-US)\n- email_version_name (option) — Template version to send (ie: Version A)\n\n### Call with REQUIRED parameters only\nThe `email_data` field is optional, but highly recommended!\n\n```python\nr = api.send(\n email_id='YOUR-TEMPLATE-ID',\n recipient={\n 'address': 'us@sendwithus.com'\n }\n)\nprint r.status_code\n# 200\n```\n\n### Call with REQUIRED parameters and email_data\n```python\nr = api.send(\n email_id='YOUR-TEMPLATE-ID',\n recipient={\n 'address': 'us@sendwithus.com'\n },\n email_data={\n 'first_name': 'Matt'\n }\n)\nprint r.status_code\n# 200\n```\n\n### Optional Sender\nThe `sender['address']` is a required sender field. `sender['name']` and `sender['reply_to']` are both optional.\n\n```python\nr = api.send(\n email_id='YOUR-TEMPLATE-ID',\n recipient={\n 'name': 'Matt',\n 'address': 'us@sendwithus.com'\n },\n email_data={\n 'first_name': 'Matt'\n },\n sender={\n 'address': 'company@company.com',\n 'reply_to':'info@company.com', # Optional\n 'name': 'Company' # Optional\n }\n)\nprint r.status_code\n# 200\n```\n\n### Optional CC\n\n```python\nr = api.send(\n email_id='YOUR-TEMPLATE-ID',\n recipient={\n 'name': 'Matt',\n 'address': 'us@sendwithus.com'\n },\n cc=[\n {'address': 'company@company.com'},\n {'address': 'info@company.com'}\n ]\n)\nprint r.status_code\n# 200\n```\n\n### Optional BCC\n\n```python\nr = api.send(\n email_id='YOUR-TEMPLATE-ID',\n recipient={\n 'name': 'Matt',\n 'address': 'us@sendwithus.com'\n },\n bcc=[\n {'address': 'company@company.com'},\n {'address': 'info@company.com'}\n ]\n)\nprint r.status_code\n# 200\n```\n\n### Optional Headers\n\n```python\nr = api.send(\n email_id='YOUR-TEMPLATE-ID',\n recipient={\n 'name': 'Matt',\n 'address': 'us@sendwithus.com'\n },\n headers={\n 'X-HEADER-ONE': 'header-value'\n }\n)\nprint r.status_code\n# 200\n```\n\n### Optional ESP Account\n\n```python\nr = api.send(\n email_id='YOUR-TEMPLATE-ID',\n recipient={\n 'name': 'Matt',\n 'address': 'us@sendwithus.com'\n },\n esp_account='YOUR-ESP-ID'\n)\nprint r.status_code\n# 200\n```\n\n### Optional File Attachments\n\n```python\nr = api.send(\n email_id='YOUR-TEMPLATE-ID',\n recipient={\n 'name': 'Matt',\n 'address': 'us@sendwithus.com'\n },\n files=[\n open('/home/Matt/report1.txt', 'r'),\n open('/home/Matt/report2.txt', 'r')\n ]\n)\nprint r.status_code\n# 200\n```\n\n### Optional File Attachments with explicit file names\n\n```python\nr = api.send(\n email_id='YOUR-TEMPLATE-ID',\n recipient={\n 'name': 'Matt',\n 'address': 'us@sendwithus.com'\n },\n files=[{\n 'file': open('/home/Matt/report1.txt', 'r'),\n 'filename': 'arbitrary_file_name.xyz'\n }]\n)\nprint r.status_code\n# 200\n```\n\n### Optional Inline Image\n\n```python\nr = api.send(\n email_id='YOUR-TEMPLATE-ID',\n recipient={\n 'name': 'Matt',\n 'address': 'us@sendwithus.com'\n },\n inline=open('image.jpg', 'r')\n)\nprint r.status_code\n# 200\n```\n\n### Optional Inline Image with explicit file names\n\n```python\nr = api.send(\n email_id='YOUR-TEMPLATE-ID',\n recipient={\n 'name': 'Matt',\n 'address': 'us@sendwithus.com'\n },\n inline={\n 'file': open('/home/Matt/image.jpg', 'r'),\n 'filename': 'cool_image.jpg'\n }\n)\nprint r.status_code\n# 200\n```\n\n### Optional Locale\n```python\nr = api.send(\n email_id='YOUR-TEMPLATE-ID',\n recipient={\n 'name': 'Matt',\n 'address': 'us@sendwithus.com'\n },\n locale='fr-FR'\n)\nprint r.status_code\n# 200\n```\n\n### Optional Version Name\n```python\nr = api.send(\n email_id='YOUR-TEMPLATE-ID',\n recipient={\n 'name': 'Matt',\n 'address': 'us@sendwithus.com'\n },\n email_version_name='Version A'\n)\nprint r.status_code\n# 200\n```\n\n# Drip Campaigns\n\n### List all Drip Campaigns\n\nList all drip campaigns for the current profile\n\n```python\napi.list_drip_campaigns()\n```\n\n### Start a Customer on a Drip Campaign\n\nStarts a customer on the first step of a specified drip campaign\n\n```python\napi.start_on_drip_campaign(\n 'dc_1234asdf1234',\n {'address': 'customer@email.com'}\n)\n```\n\n### Start a Customer on a Drip Campaign with email_data\n\nYou may specify extra data to be merged into the templates in the drip campaign.\n\n*Note* \u2014 Any data provided in the `email_data` parameter for `start_on_drip_campaign()` will be used throughout the entire drip campaign.\n\n```python\napi.start_on_drip_campaign(\n 'dc_1234asdf1234',\n {'address': 'customer@email.com'},\n email_data={'color': 'blue'},\n sender={'address': 'from@email.com'},\n cc=[{'address': 'cc@email.com'}],\n tags=['tag_one', 'tag_two'],\n esp_account='esp_1234',\n locale='fr-FR'\n)\n```\n\n### Remove a Customer from a Drip Campaign\n\nDeactivates all pending emails for a customer on a specified drip campaign\n\n```python\napi.remove_from_drip_campaign(\n 'customer@email.com',\n 'dc_1234asdf1234'\n)\n```\n\n### Remove a Customer from all Drip Campaigns\n\nYou can deactivate all pending drip campaign emails for a customer\n\n```python\napi.drip_deactivate(\n 'customer@example.com'\n)\n```\n\n### Remove a Customer from a Single Drip Campaigns\n\n```python\napi.remove_from_drip_campaign(\n 'customer@example.com',\n 'dc_1234asdf1234'\n)\n```\n\n### List the details of a specific Drip Campaign\n\n```python\napi.drip_campaign_details(\n 'dc_1234asdf1234'\n)\n```\n\n# Customers\n\n### Get a Customer\n\n```python\napi.customer_details(\n 'customer@example.com'\n)\n```\n\n### Create/Update Customer\n\nYou can use the same endpoint to create or update a customer. Sendwithus\nwill perform a merge of the data on the customer profile, preferring the new data.\n\n```python\napi.customer_create(\n 'customer@example.com',\n data={\n 'first_name': 'Matt'\n }\n)\n```\n\n\n### Delete a Customer\n\n```python\napi.customer_delete(\n 'customer@example.com'\n)\n```\n\n# Snippets\n\n### Get All Snippets\n\n```python\napi.snippets()\n```\n\n### Get a Specific Snippet\n\n```python\napi.get_snippet(\n 'snp_1234asdf1234'\n)\n```\n\n### Create a Snippet\n\n```python\napi.create_snippet(\n name='My Snippet',\n body='