README

Maileon API 客户端

提供连接到 XQueue Maileon 的 REST API 的 API 客户端，并将所有 API 函数和数据（反）序列化，以便在 PHP 项目中更容易使用。

Maileon 的 REST API 文档可以在这里找到。

要求

API 客户端需要 PHP >= 7.0 以及 libxml 和 libcurl。

此外，所有请求都使用 SSL 加密的 API 端点。要在 CURL 中启用 SSL 支持，请按照以下步骤操作：

从https://curl.haxx.se/ca/cacert.pem 下载 CURL 的官方 SSL 证书捆绑包
将捆绑包保存到可以由您的 PHP 安装访问的目录中
将以下条目添加到您的 php.ini 文件中（请记住将路径更改为您放置证书捆绑包的位置）

curl.cainfo="your-path-to-the-bundle/cacert.pem"

安装

您可以使用 Composer 将此库添加到您的项目中

composer require xqueue/maileon-api-client

使用

API 客户端将 Maileon 的 REST API 功能划分为特定的可消费服务。每个服务都提供其特定类别的所有功能。

以下服务可用：

联系人 读取、订阅、编辑、取消订阅或删除联系人。如果需要，可对单个联系人或批量请求进行操作。
黑名单 管理您的黑名单。
联系人筛选器 根据筛选规则对地址池进行分段。
目标组 管理分发列表以指定谁将收到哪些邮件。
报告获取有关您的邮件发送和联系人池的一般报告的所有 KPI 信息。
邮件发送 管理和控制您的邮件发送。
事务管理事务端点（事件）或发送新事务以触发发送或营销自动化程序。
营销自动化 启动预定义的营销自动化程序。
账户配置特定的账户功能。
媒体管理邮件模板。
Webhooks 管理自动数据分发以通知外部系统特定事件。

示例

联系人示例

请求由电子邮件地址标识的基本 联系人数据

<?php

use de\xqueue\maileon\api\client\contacts\ContactsService;

require __DIR__ . '/vendor/autoload.php';

$contactsService = new ContactsService([
    'API_KEY' => 'Your API key',
]);

$contact = $contactsService->getContactByEmail('foo@bar.com')->getResult();

/**
* The contact object stores all information you requested.
* 
* Identifiers (Maileon ID, Maileon external id and email address), marketing permission
* level, creation date and last update date are always included if they are set in Maileon.
* 
* ID: $contact->id
* Email: $contact->email
* Permission: $contact->permission->getType()
*/

请求一个由其电子邮件地址标识的联系人，包括其姓名和预定义的自定义字段，并检查有效的响应

<?php

use de\xqueue\maileon\api\client\contacts\ContactsService;
use de\xqueue\maileon\api\client\contacts\StandardContactField;

require __DIR__ . '/vendor/autoload.php';

$contactsService = new ContactsService([
    'API_KEY' => 'Your API key',
]);

$getContact = $contactsService->getContactByEmail(
    email:'foo@bar.com',
    standard_fields:[
        StandardContactField::$FIRSTNAME,
        StandardContactField::$LASTNAME,
    ],
    custom_fields:[
        'My custom field in Maileon',
    ]
);

if (!$getContact->isSuccess()) {
    die($getContact->getResultXML()->message);
}

$contact = $getContact->getResult();

/**
 * The contact object stores all information you requested.
 * 
 * Identifiers (Maileon ID, Maileon external id and email address), marketing permission
 * level, creation date and last update date are always included if they are set in Maileon.
 * 
 * ID: $contact->id
 * Email: $contact->email
 * Permission: $contact->permission->getType()
 * First name: $contact->standard_fields[StandardContactField::$FIRSTNAME];
 * Custom field: $contact->custom_fields['My custom field in Maileon'];
 */

在 Maileon 中创建一个联系人

<?php

use de\xqueue\maileon\api\client\contacts\ContactsService;
use de\xqueue\maileon\api\client\contacts\Contact;
use de\xqueue\maileon\api\client\contacts\Permission;
use de\xqueue\maileon\api\client\contacts\Preference;
use de\xqueue\maileon\api\client\contacts\StandardContactField;
use de\xqueue\maileon\api\client\contacts\SynchronizationMode;

require __DIR__ . '/vendor/autoload.php';

$contactsService = new ContactsService([
    'API_KEY' => 'Your API key',
]);

$contact = new Contact(
    email:'foo@bar.com',
    standard_fields:[
        StandardContactField::$FIRSTNAME => 'Foo',
        StandardContactField::$LASTNAME => 'Bar',
    ],
    custom_fields:[
        'My custom field in Maileon' => 'A value corresponding to the field type',
    ],
);

$creation = $contactsService->createContact(
    contact:$contact,
    syncMode:SynchronizationMode::$IGNORE,
    src:'An optional source of the contact creation',
    subscriptionPage:'An additional source of the contact creation',
    doi:true,
    doiPlus:true, // Enable single user tracking with the DOI process
    doiMailingKey:'A key to identify the DOI mailing',
);

if (!$creation->isSuccess()) {
    die($creation->getResultXML()->message);
}

批量同步较大的联系人列表

<?php

use de\xqueue\maileon\api\client\contacts\ContactsService;
use de\xqueue\maileon\api\client\contacts\Contacts;
use de\xqueue\maileon\api\client\contacts\Contact;
use de\xqueue\maileon\api\client\contacts\Permission;
use de\xqueue\maileon\api\client\contacts\SynchronizationMode;
use de\xqueue\maileon\api\client\contacts\StandardContactField;

require __DIR__ . '/vendor/autoload.php';

$contactsService = new ContactsService([
    'API_KEY' => 'Your API key',
]);

$contactList = new Contacts();

for ($i=1; $i<=10000; $i++) {
    $contactList->addContact(
        new Contact(
            email:"foo-{$i}@bar.com",
            standard_fields:[
                StandardContactField::$FIRSTNAME => 'Foo',
                StandardContactField::$LASTNAME => 'Bar',
            ],
            custom_fields:[
                'My custom field in Maileon' => 'A value corresponding to the field type',
            ],
        )
    );
}

$response = $contactsService->synchronizeContacts(
    contacts:$contactList,
    syncMode:SynchronizationMode::$IGNORE,
    useExternalId:false,
    ignoreInvalidContacts:true,
    reimportUnsubscribedContacts:false,
    overridePermission:false,
    updateOnly:false,
);

// The response contains some statistics and, if ignore_invalid_contacts is set
// to true, information about possibly failed contact creations, see
// https://maileon.com/support/synchronize-contacts/#articleTOC_3

报告示例

打印所有取消订阅

<?php

use de\xqueue\maileon\api\client\reports\ReportsService;

require __DIR__ . '/vendor/autoload.php';

$contactsService = new ReportsService([
    'API_KEY' => 'Your API key',
]);

$index = 1;
do {
    $getUnsubscribers = $contactsService->getUnsubscribers(
        pageIndex:$index++,
        pageSize:1000
    );
    
    foreach ($getUnsubscribers->getResult() as $unsubscriber) {
        printf('%s unsusbcribed in mailing %u at %s'.PHP_EOL,
            $unsubscriber->contact->email,
            $unsubscriber->mailingId,
            $unsubscriber->timestamp
        );
    }
} while($getUnsubscribers->getResponseHeaders()['X-Pages'] >= $index);

获取特定邮件发送的 KPI 数据

<?php

use de\xqueue\maileon\api\client\reports\ReportsService;

require __DIR__ . '/vendor/autoload.php';

$reportsService = new ReportsService([
    'API_KEY' => 'Your API key',
]);

$mailingId = 123;

$recipients = $reportsService->getRecipientsCount(mailingIds:[$mailingId])->getResult();
$opens = $reportsService->getOpensCount(mailingIds:[$mailingId])->getResult();
$clicks = $reportsService->getClicksCount(mailingIds:[$mailingId])->getResult();
$unsubscribers = $reportsService->getUnsubscribersCount(mailingIds:[$mailingId])->getResult();
$conversions = $reportsService->getConversionsCount(mailingIds:[$mailingId])->getResult();

邮件发送示例

创建一个新的邮件发送，添加自定义 HTML 内容，附加目标组并立即发送

<?php

use de\xqueue\maileon\api\client\mailings\MailingsService;

require __DIR__ . '/vendor/autoload.php';

$mailingsService = new MailingsService([
    'API_KEY' => 'Your API key',
]);

$mailingId = $mailingsService->createMailing(
    name:'My campaign name',
    subject:'Hi [CONTACT|FIRSTNAME]! We got some news for you!'
)->getResult();

$mailingsService->setSender($mailingId, 'foo@bar.com');
$mailingsService->setSenderAlias($mailingId, 'Maileon news team');
$mailingsService->setHTMLContent(
    mailingId:$mailingId,
    html:'<html>...</html>',
    doImageGrabbing:true,
    doLinkTracking:true
);
$mailingsService->setTargetGroupId($mailingId, 123);
$mailingsService->sendMailingNow($mailingId);

事务示例

发送包含产品信息作为订单确认的新事务

<?php

use de\xqueue\maileon\api\client\transactions\ContactReference;
use de\xqueue\maileon\api\client\transactions\Transaction;
use de\xqueue\maileon\api\client\transactions\TransactionsService;

require __DIR__ . '/vendor/autoload.php';

$transactionsService = new TransactionsService([
    'API_KEY' => 'Your API key',
]);

$transaction = new Transaction(
    typeName:'My event to trigger',
    contact:new ContactReference(
        email:'foo@bar.com'
    ),
    content:[
        'foo' => 'bar',
        'items' => [
            [
                'name' => 'foo',
                'quantity' => 2,
                'price' => 27.99
            ],
            [
                'name' => 'bar',
                'quantity' => 1,
                'price' => 16.49
            ],
        ],
    ]
);

$transactionsService->createTransactions([$transaction]);

xqueue / maileon-api-client

维护者

详细信息