sendwithus.com 的 Python API 客户端

项目描述

sendwithus python客户端

要求

Python 请求库

安装

pip install sendwithus

用法

对于所有示例，假设：

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

错误处理

默认情况下，API 调用返回一个响应对象。但是，您可以使用 sendwithus.api(api_key='YOUR-API-KEY', raise_errors=True)which 会引发以下错误：

AuthenticationError- 由无效的 API 密钥引起
APIError- 由无效的 API 请求引起（4xx 错误）
ServerError- 由服务器错误（5xx 错误）引起

可以从sendwithus.exceptions模块中导入错误。

模板

获取您的模板

api.templates()

获取特定模板

api.get_template(
    'YOUR-TEMPLATE-ID'
)

获取特定模板版本

api.get_template(
    'YOUR-TEMPLATE-ID',
    version='YOUR-VERSION-ID'
)

创建模板

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

创建新的语言环境

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

创建新版本

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

更新模板版本

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

我们验证所有 HTML，如果它无效将返回错误。

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

发送

注意- 如果指定的电子邮件（收件人地址）不存在客户，则发送调用将创建一个客户。

email_id - 要发送的模板 ID
接受者
- address - 收件人的电子邮件地址
- name (optional) — 收件人的姓名
email_data（可选）- 包含电子邮件模板数据的对象
发件人（可选）
- address - 发件人的电子邮件地址
- reply_to — 发件人的回复地址
- name - 发件人的姓名
cc（可选）- 抄送收件人列表，格式为 {'address': ' cc@email.com '}
bcc（可选）- 密件抄送收件人列表，格式为 {'address': ' bcc@email.com '}
headers (options) — 对象包含要包含在电子邮件中的 SMTP 标头
esp_account（可选）— 发送此电子邮件的 ESP 帐户的 ID。例如：esp_1a2b3c4d5e
文件（可选）- 文件附件列表（组合最大 7MB）
inline (optional) - 内联附件对象
locale (optional) — 要发送的模板语言环境（即：en-US）
email_version_name (option) — 要发送的模板版本（即：版本 A）

仅使用 REQUIRED 参数调用

该email_data字段是可选的，但强烈推荐！

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

使用 REQUIRED 参数和 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

可选发件人

这sender['address']是一个必填的发件人字段。sender['name']并且sender['reply_to']都是可选的。

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

可选抄送

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

可选密件抄送

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

可选标题

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

可选的 ESP 帐户

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

可选文件附件

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

具有显式文件名的可选文件附件

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

可选的内嵌图像

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

具有显式文件名的可选内联图像

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

可选语言环境

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

可选版本名称

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

滴灌运动

列出所有滴灌广告系列

列出当前配置文件的所有滴灌活动

api.list_drip_campaigns()

在滴灌活动中吸引客户

在指定滴灌活动的第一步启动客户

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

使用 email_data 启动客户的水滴营销活动

您可以指定要合并到滴灌活动模板中的额外数据。

注意&emdash; email_data参数中提供的任何数据start_on_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'
)

从水滴营销中删除客户

在指定的滴灌活动中停用客户的所有待处理电子邮件

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

从所有滴灌活动中删除客户

您可以为客户停用所有待处理的滴灌活动电子邮件

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

从单次滴灌活动中删除客户

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

列出特定滴灌活动的详细信息

api.drip_campaign_details(
    'dc_1234asdf1234'
)

顾客

获得客户

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

创建/更新客户区域设置

您可以使用相同的端点来创建或更新客户。这主要用于将区域设置与电子邮件地址相关联，以便 Sendwithus 可以自动向他们发送正确的模板。请注意，如果您的模板仅使用一种语言，则无需使用此功能。

api.customer_create(
    'customer@example.com',
    locale="fr-FR"
)

删除客户

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

片段

获取所有片段

api.snippets()

获取特定片段

api.get_snippet(
    'snp_1234asdf1234'
)

创建片段

api.create_snippet(
    name='My Snippet',
    body='<h1>Snippets!</h1>'
)

更新片段

api.update_snippet(
    'snp_1234asdf1234',
    name='My Snippet',
    body='<h1>Snippets!</h1>'
)

国际化 (i18n) API

获取翻译包（.pot 文件）

api.get_translation_template(
    `my_translation_tag`
)

发布翻译后的字符串和 .po 文件

with open('my_translation_file', 'rb') as f:
    api.create_translation_file(
        `my_translation_tag`,
        f.read()
    )

使成为

使用数据渲染模板

Render API 允许您使用 Sendwithus 在发送电子邮件时使用的完全相同的渲染工作流来渲染带有数据的模板。 Strict设置False为默认值，如果Strict=True此 API 调用在任何缺少email_data的 .

api.render(
    email_id='YOUR-TEMPLATE-ID',
    email_data={
        'amount': '$12.00'
    },
    locale='fr-FR',
    version_name='French-Version',
    strict=False
)

批处理 API

Sendwithus 的 API 有一个批处理端点，可以接受多个请求并同时执行它们。 请注意，Sendwithus 建议将批处理请求保持在 10 个或更少。

创建和执行批处理请求

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

预期响应

成功

    >>> r.status_code
    200

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

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

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

错误案例

格式错误的请求

    >>> r.status_code
    400

错误的 API 密钥

    >>> r.status_code
    403

运行测试

使用tox运行测试：

tox

测试多个 Python 版本

这假设您已安装tox并使用 pyenv安装多个版本的 python。

一旦安装了所有支持的 python 版本，只需运行：

tox

这将针对所有指定的版本运行测试tox.ini。

故障排除

一般故障排除

启用调试模式
确保您使用的是最新的 Python 客户端
捕获响应数据并检查您的日志——这通常会有确切的错误

启用调试模式

调试模式打印出底层请求信息以及发送到 Sendwithus 的数据负载。您很可能会在日志中找到此信息。要启用它，只需DEBUG=True在实例化 API 对象时作为参数输入。使用调试模式比较发送到Sendwithus 的 API 文档的数据负载。

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

响应范围

Sendwithus 的 API 通常会在以下范围内发回响应：

2xx&emdash; 请求成功
4xx &emdash; 请求失败（客户端错误）
5xx &emdash; 请求失败（服务器错误）

如果您在 400 响应范围内收到错误，请按照以下步骤操作：

仔细检查传递给 Sendwithus 的数据和 ID
确保您的 API 密钥正确
记录并检查响应的正文

内部的

打包

  python setup.py sdist bdist_wheel upload

项目详情

发布历史发布通知| RSS订阅

这个版本

5.3.0

2022 年 7 月 14 日

5.2.2

2020 年 5 月 22 日

5.2.1

2020 年 4 月 21 日

5.2.0

2020 年 4 月 16 日

5.1.0

2019 年 3 月 8 日

5.0.0

2017 年 8 月 8 日

4.1.0

2017 年 5 月 23 日

2.0.0

2017 年 1 月 26 日

1.10.0

2017 年 1 月 18 日

1.9.0

2017 年 1 月 12 日

1.8.1

2016 年 10 月 26 日

1.8.0

2015 年 11 月 27 日

1.7.0

2015 年 11 月 19 日

1.6.6

2015 年 10 月 25 日

1.6.5

2015 年 5 月 25 日

1.5.5

2015 年 5 月 18 日

1.5.3

2015 年 2 月 26 日

1.4.3

2015 年 2 月 18 日

sendwithus 5.3.0

导航

项目链接

统计数据

Meta

Maintainers

分类