README

为Smart emailing API提供的API包装器。

安装
用法
支持
高级文档
贡献或覆盖
升级
版权和许可
智能邮件发送API

安装

需求

此包需要PHP 7.4或更高版本。

通过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->importRequest()->addContact(new Contact('test@test.cz'))->send();

或者

// Creates a new instance
$import = $api->importRequest();
$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();

错误处理

在发送任何请求时，您可以捕获错误异常RequestException。

use SmartEmailing\v3\Exceptions\RequestException;

try {
    $api->ping();
} 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
}

支持

高级文档

导入联系人

导入包含2个主要数据点

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

用法示例见上方。

联系人

导入包含3个主要数据点

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

请参阅源代码以了解您可以使用的所有方法和属性

自定义字段和联系人列表

使用具有create/add/get/isEmpty/toArray/jsonSerialize方法的data holder。

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

导入订单

导入包含2个主要数据点

设置$import->settings()->setSkipInvalidOrders(true)
订单$import->newOrder() : Order、$import->orders() : array和$import->addOrder($order) : self

用法示例见上方。

自定义字段

自定义字段使用与自定义字段相关的每个请求的包装器。要创建新实例，请调用$api->customFields()。在此对象上，您可以创建任何当前已实现的请求。以下为示例。

创建

一种快速的方法，它将创建带有所需自定义字段的请求

use SmartEmailing\v3\Models\CustomFieldDefinition;

...
// Create the new customField and send the request now.
$customField = new CustomFieldDefinition('test', CustomFieldDefinition::TEXT);
$data = $api->customFields()->create($customField);

 // Get the customField in data
$customFieldId = $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();
$data = $response->data();
$customFieldId = $data->id;

搜索/列表

API文档

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

响应

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

获取不带高级搜索的列表

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

$data = $api->customFields()->list();

/** @var \SmartEmailing\v3\Models\CustomFieldDefinition $customField */
foreach ($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();
$data = $response->data();

请求方法

获取器通过公共属性进行
- 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()->getByName('name')) {
    return $customField->id;
} else {
    throw new Exception('Not found!', 404);
}

发送 / 事务性电子邮件

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

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

$transactionEmail = $api->transactionalEmailsRequest();

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

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

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

完整的自定义电子邮件示例

$transactionEmail = $api->customEmailsBulkRequest();

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

发送 / 批量自定义短信

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

完整的发送短信示例

$bulkCustomSms = $api->customSmsBulkRequest();

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

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

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

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

$bulkCustomSms->setTag('tag_tag');
$bulkCustomSms->setSmsId(5);
$bulkCustomSms->addTask($task);

$bulkCustomSms->send();

升级

有关如何升级到新版本的说明，请参阅 UPGRADE.md。

贡献或覆盖

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

版权和许可

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

pion / smart-emailing-v3

维护者

详细信息