README

Smart emailing API的API包装器。目前处于开发中。

安装
使用
支持
高级文档
变更日志
贡献或覆盖
版权和许可
Smart emailing API

安装

需求

此包需要PHP 7.3及以上版本。

通过composer安装

composer require pion/smart-emailing-v3

使用

使用您的用户名和apiKey创建Api实例。

use SmartEmailing\v3\Api;

...
$api = new Api('username', 'api-key');

然后使用$api和所需的方法/组件。

// Creates a new instance
$api->import()->addContact(new Contact('test@test.cz'))->send();

或者

// Creates a new instance
$import = $api->import();
$contact = new Contact('test@test.cz');
$contact->setName('Martin')->setNameDay('2017-12-11 11:11:11');
$import->addContact($contact);

// Create new contact that will be inserted in the contact list
$contact2 = $import->newContact('test2@test.cz');
$contact2->setName('Test');

// Create new contact that will be inserted in the contact list
$import->newContact('test3@test.cz')->setName('Test');
$import->send();

错误处理

在请求类中，当使用send()方法时，您可以捕获错误异常RequestException。

use SmartEmailing\v3\Exceptions\RequestException;

try {
    $api->ping()->send();
} catch (RequestException $exception) {
    $exception->response(); // to get the real response, will hold status and message (also data if provided)
    $exception->request(); // Can be null if the request was 200/201 but API returned error status text
}

支持

导入$api->import()或new Import($api)
Ping $api->ping()或new Ping($api)
凭证 $api->credentials()或new Credentials($api)
联系人列表检索列表$api->contactlist()->lists()或详情$api->contactlist()->get($id) - 2个请求对象的包装器
自定义字段 - exists: 通过名称快速获取自定义字段。 $api->customFields()->exists('name') : CustomField|bool
自定义字段 - 创建创建请求$api->customFields()->createRequest()或发送创建请求$api->customFields()->create(new CustomField('test', CustomField::TEXT))
自定义字段 - 搜索/列表搜索请求$api->customFields()->searchRequest($page = 1, $limit = 100)或发送搜索请求$api->customFields()->search($page = 1, $limit = 100)
自定义字段 - REST类似于联系人列表的概念 - 已开始
自定义字段选项
联系人类似于联系人列表的概念
列表中的联系人类似于联系人列表的概念
自定义电子邮件
电子邮件
通讯录
Webhooks

高级文档

导入

导入包含2个主要数据点

设置$import->settings()->setUpdate(true)
联系人$import->newContact() : Contact、$import->contacts() : array和$import->addContact() : $this

用法示例见上方。

联系人

导入包含3个主要数据点

所有数据都可以通过公共属性访问。流畅的设置方法具有基本的验证和日期转换逻辑
自定义字段$contact->customFields()用于添加新字段
联系人列表$contact->contactLists()用于添加新的联系人列表

请查看源代码以获取您可以使用的所有方法和属性

自定义字段和联系人列表

使用具有create/add/get/isEmpty/toArray/jsonSerialize方法的数据持有者。

$field = $contact->customFields()->create(12, 'test')
$list = $contact->contactLists()->create(12, 'confirmed')

自定义字段

自定义字段使用了包装器来处理每个与自定义字段相关的请求。要创建一个新的实例，请调用 $api->customFields()。在这个对象上，您可以创建任何当前已实现的请求。下面是具体说明。

创建

快速创建带有所需自定义字段的请求的方法

use SmartEmailing\v3\Request\CustomFields\CustomField;
use SmartEmailing\v3\Request\CustomFields\Create\Response;

...
// Create the new customField and send the request now.
$response = $api->customFields()->create(new CustomField('test', CustomField::TEXT));
    
 // Get the customField in data
$customFieldId = $response->data()->id;

或者

$request = $api->customFields()->createRequest(); // You can pass the customField object

// Setup customField
$customField = new CustomField();
$request->setCustomField($customField);

// Setup data
$customField->setType(CustomField::RADIO)->setName('test');

// Send the request
$response = $request->send();

搜索 / 列表

API 文档

启用通过自定义字段进行搜索，并支持过滤/排序。每页结果限制为 100。通过调用 $response->data() 返回元数据（MetaDataInterface）和 CustomField\CustomField 数组。

响应

data() 返回 CustomField\CustomField 数组
meta() 返回一个具有属性（在 MetaDataInterface 中定义）的 stdClass

获取不带高级设置的列表

创建搜索请求，并仅设置 $page 或 $limit。完整的 api 响应包括 customfield_options_url 或

$response = $api->customFields()->search($page = 1);

/** @var \SmartEmailing\v3\Request\CustomFields\CustomField $customField */
foreach ($response->data() as $customField) {
    echo $customField->id;
    echo $customField->name;
    echo $customField->type;
}

高级设置 - 过滤/排序等

$request = $api->customFields()->searchRequest(1);

// Search by name
$request->filter()->byName('test');
$request->sortBy('name');

// Send the request
$response = $request->send();

请求方法

通过公共属性获取器
- page
- limit
- select
- expand
- sort
流畅的设置器（带有验证） - 下面将详细介绍。
filter() 返回一个设置好的过滤器 - 下面将详细介绍

expandBy(string : $expand)

使用此参数，"customfield_options_url" 属性将被 "customfield_options" 替换，包含扩展数据。下面有示例。更多信息请参阅 "/customfield-options" 端点。

允许的值："customfield_options"

select(string : $select)

逗号分隔的属性选择列表。例如："?select=id,name" 如果不提供，则选择所有字段。

允许的值："id"，"name"，"type"

sortBy(string : $sort)

从左侧的排序键的逗号分隔列表。任何键前缀为 "-" 表示降序方向，例如："?sort=type,-name"

允许的值："id"，"name"，"type"

setPage(int : $page)

设置当前页

limit(int : $limit)

设置单次查询的结果限制

filter()

允许使用多个过滤条件过滤自定义字段。

通过公共属性获取器
- name
- type
- id
流畅的设置器（带有验证）
- byName($value)
- byType($value)
- byId($value)

存在

运行带有名称过滤器的搜索查询并检查给定的名称是否在自定义字段中。返回 false 或 CustomFields\CustomField。使用发送逻辑（抛出 RequestException）。

// Can throw RequestException - uses send.
if ($customField = $api->customFields()->exists('name')) {
    return $customField->id;
} else {
    throw new Exception('Not found!', 404);
}

发送 / 事务性电子邮件

send/transactional-emails-bulk API 调用的实现：[链接](https://app.smartemailing.cz/docs/api/v3/index.html#api-Custom_campaigns-Send_transactional_emails)

完整的交易性电子邮件示例

$transactionEmail = new TransactionalEmails($api);

$credentials = new SenderCredentials();
$credentials->setFrom('from@example.com');
$credentials->setReplyTo('to@example.com');
$credentials->setSenderName('Jean-Luc Picard');

$recipient = new Recipient();
$recipient->setEmailAddress('kirk@example.com');

$replace1 = new Replace();
$replace1->setKey('key1');
$replace1->setContent('content1');

$replace2 = new Replace();
$replace2->setKey('key2');
$replace2->setContent('content2');

$templateVariable = new TemplateVariable();
$templateVariable->setCustomData([
    'foo' => 'bar',
    'products' => [
        ['name' => 'prod1', 'desc' => 'desc1'],
        ['name' => 'prod1', 'desc' => 'desc2']
    ]
]);

$attachment1 = new Attachment();
$attachment1->setContentType('image/png');
$attachment1->setFileName('picture.png');
$attachment1->setDataBase64('data1');

$attachment2 = new Attachment();
$attachment2->setContentType('image/gif');
$attachment2->setFileName('sun.gif');
$attachment2->setDataBase64('data2');

$task = new Task();
$task->setRecipient($recipient);
$task->addReplace($replace1);
$task->addReplace($replace2);
$task->setTemplateVariables($templateVariable);
$task->addAttachment($attachment1);
$task->addAttachment($attachment2);

$messageContents = new MessageContents();
$messageContents->setTextBody('text_body');
$messageContents->setHtmlBody('html_body');
$messageContents->setSubject('subject');

$transactionEmail->setTag('tag_tag');
$transactionEmail->setEmailId(5);
$transactionEmail->setSenderCredentials($credentials);
$transactionEmail->addTask($task);
$transactionEmail->setMessageContents($messageContents);

$transactionEmail->send();

发送 / 批量自定义电子邮件

send/custom-emails-bulk API 调用的实现：[链接](https://app.smartemailing.cz/docs/api/v3/index.html#api-Custom_campaigns-Send_bulk_custom_emails)

完整的交易性电子邮件示例

$transactionEmail = new BulkCustomEmails($api);

$credentials = new SenderCredentials();
$credentials->setFrom('from@example.com');
$credentials->setReplyTo('to@example.com');
$credentials->setSenderName('Jean-Luc Picard');

$recipient = new Recipient();
$recipient->setEmailAddress('kirk@example.com');

$replace1 = new Replace();
$replace1->setKey('key1');
$replace1->setContent('content1');

$replace2 = new Replace();
$replace2->setKey('key2');
$replace2->setContent('content2');

$templateVariable = new TemplateVariable();
$templateVariable->setCustomData([
    'foo' => 'bar',
    'products' => [
        ['name' => 'prod1', 'desc' => 'desc1'],
        ['name' => 'prod1', 'desc' => 'desc2']
    ]
]);

$task = new Task();
$task->setRecipient($recipient);
$task->addReplace($replace1);
$task->addReplace($replace2);
$task->setTemplateVariables($templateVariable);

$transactionEmail->setTag('tag_tag');
$transactionEmail->setEmailId(5);
$transactionEmail->setSenderCredentials($credentials);
$transactionEmail->addTask($task);

$transactionEmail->send();

变更日志

0.1.8

为联系人添加了目的。

0.1.7

修复了确认请求的错误命名空间。

0.1.6

将确认请求添加到导入设置中。

0.1.5

从 Contact.php 中删除了过时的 API 使用：addContactList 和 newContactList

0.1.4

自定义字段只能导入一次（按 id 唯一）

0.1.3

添加了联系人导入的自动分块发送 - 当联系人数量超过 500 时，send() 方法将发送多个请求（分块发送联系人数组）

0.1.2

添加了存在自定义字段请求。快速获取通过名称的自定义字段的方法。 $api->customFields()->exists('name') : CustomField|bool
联系人列表仅允许唯一 id（如果已添加，则忽略该值）

0.1.1

删除了 Import\Contact\CustomField 的过时方法（newCustomField, setCustomFields, addCustomField）
向 CustomFields\CustomField 添加了 createValue，以便快速创建导入的自定义字段。
将 Create 请求和响应移动到其自己的命名空间 SmartEmailing\v3\Request\CustomFields\Create，并重命名为仅 Request 类
修改了JSON结构，从array改为stdClass。更新所有json()的使用。
增加了自定义字段的搜索请求。

0.1

增加了自定义字段的创建请求。

贡献或覆盖

有关如何贡献更改，请参阅CONTRIBUTING.md。所有贡献都受欢迎。

版权和许可

smart-emailing-v3 由 Martin Kluska 编写，并发布在 MIT许可证下。

jan-suchanek / smart-emailing-v3

维护者

详细信息

README

安装

使用

错误处理

支持

高级文档

导入

联系人

自定义字段和联系人列表

自定义字段

创建

搜索 / 列表

响应

获取不带高级设置的列表

高级设置 - 过滤/排序等

请求方法

expandBy(string : $expand)

select(string : $select)

sortBy(string : $sort)

setPage(int : $page)

limit(int : $limit)

filter()

存在

发送 / 事务性电子邮件

完整的交易性电子邮件示例

发送 / 批量自定义电子邮件

完整的交易性电子邮件示例

变更日志

0.1.8

0.1.7

0.1.6

0.1.5

0.1.4

0.1.3

0.1.2

0.1.1

0.1

贡献或覆盖

版权和许可