README

本包包含用于与Mailcoach一起工作的PHP SDK。支持自托管（v6及以上）和托管Mailcoach（即Mailcoach Cloud）。使用本包可以管理电子邮件列表、订阅者和活动。

以下是一些示例

$mailcoach = new \Spatie\MailcoachSdk\Mailcoach('<api-key>', '<mailcoach-api-endpoint>')

// creating a campaign
$campaign = $mailcoach->createCampaign([
    'email_list_uuid' => 'use-a-real-email-list-uuid-here',
    'name' => 'My new campaign',
    'fields' => [
        'title' => 'The title on top of the newsletter',
        'content' => '# Welcome to my newsletter',
    ],
]);

// sending a test of the campaign to the given email address
$campaign->sendTest('john@example.com');

// sending a campaign
$campaign->send();

默认情况下，Mailcoach的端点将分页，每页最多1000项。该包使处理分页资源变得简单。只需调用->next()即可获取下一页。

// listing all subscribers of a list
$subscribers = $mailcoach->emailList('use-a-real-email-list-uuid-here')->subscribers();

do {
    foreach($subscribers as $subscriber) {
        echo $subscriber->email;
    }
} while($subscribers = $subscribers->next())

支持我们

我们投入了大量资源来创建最好的开源包。您可以通过购买我们的付费产品之一来支持我们。

我们非常感谢您从家乡寄给我们明信片，并说明您正在使用我们的哪个包。您可以在我们的联系页面上找到我们的地址。我们将所有收到的明信片发布在我们的虚拟明信片墙上。

安装

您可以通过composer安装此包

composer require spatie/mailcoach-sdk-php

您还必须安装Guzzle

composer require guzzlehttp/guzzle

用法

要开始，您必须首先创建一个Spatie\MailcoachSdk\Mailcoach实例

use Spatie\MailcoachSdk\Mailcoach;

$mailcoach = new Mailcoach('<your-api-key>', '<your-mailcoach-api-endpoint>')

您可以在Mailcoach设置的“API令牌”屏幕中找到API密钥和Mailcoach API端点。

处理分页

有几个方法，如emailLists()、'subscribers()'和campaigns()，将返回分页结果。要获取结果的下一次页面，只需在结果上调用next()。如果没有更多结果，则该方法返回null。

以下是显示列表中每个订阅者电子邮件地址的方法

$subscribers = $mailcoach->subscribers('<email-list-uuid');

do {
    foreach($subscribers as $subscriber) {
        echo $subscriber->email;
    }
} while($subscribers = $subscribers->next())

在分页结果中，例如上面的$subscribers，还有一些其他方便的方法

results()：获取结果。结果对象也是可迭代的，因此您也可以通过简单地在循环中使用对象来获取结果
next()：获取结果的下一页
previous()：获取结果的上一页
currentPage()：获取当前页码
total()：获取所有页面的结果总数
nextUrl()：获取获取下一页结果的URL
previousUrl()：获取获取上一页结果的URL

与电子邮件列表一起工作

以下是获取所有电子邮件列表的方法

$emailLists = $mailcoach->emailLists();

您可以获取单个电子邮件列表

$emailList = $mailcoach->emailList('<uuid-of-email-list>');

以下是如何创建电子邮件列表

$mailcoach->createEmailList(['name' => 'My new email list']);

您可以获取电子邮件列表的属性

$emailList->name;
$emailList->uuid;
// ...

查看Spatie\MailcoachSdk\Resources\EmailList的源代码以查看可用的属性列表。

您可以通过更改属性之一并调用save()来更新电子邮件列表。

$emailList->name = 'Updated name';
$emailList->save();

您可以调用delete()来删除电子邮件列表。

$emailList->delete();

与订阅者一起工作

要获取列表中的所有订阅者，您可以在电子邮件列表上调用 subscribers() 方法。

$subscribers = $mailcoach
   ->emailList('<uuid-of-email-list>')
   ->subscribers();

可选地，您可以将过滤器传递给 subscribers() 方法。以下是如何获取所有使用Gmail地址订阅的订阅者。

$subscribers = $mailcoach
   ->emailList('<uuid-of-email-list>')
   ->subscribers(['email' => 'gmail.com']);

或者，您也可以在 $mailcoach 上调用 subscribers()。

$subscribers = $mailcoach->subscribers('<uuid-of-email-list>', $optionalFilters);

还有一个便捷的方法可以快速从列表中获取订阅者。

// returns instance of Spatie\MailcoachSdk\Resources\Subscriber
// or null if the subscriber does not exist.

$subscriber = $emaillist->subscriber('john@example.com');

或者，您可以通过UUID获取订阅者。

$subscriber = $mailcoach->subscriber('<subscriber-uuid>');

这是创建订阅者的方法。

$subscriber = $mailcoach->createSubscriber('<email-list-uuid>', [
    'email' => 'john@example.com',
]);

您可以获取订阅者的属性。

$subscriber->firstName;
$subscriber->email;
// ...

查看 Spatie\MailcoachSdk\Resources\Subscriber 的源代码，以了解可用属性列表。

您可以通过更改属性之一并调用 save() 来更新订阅者。

$subscriber->firstName = 'Updated name';
$subscriber->save();

您可以通过调用这些方法来确认、取消订阅、重新订阅、删除订阅者以及添加或删除标签。

$subscriber->confirm();
$subscriber->unsubscribe();
$subscriber->resubscribe();
$subscriber->delete();
$subscriber->addTags(['abandoned-cart', 'product-updates']);
$subscriber->removeTags(['abandoned-cart', 'product-updates']);

与活动相关的工作

以下是获取所有活动的示例。

$campaigns = $mailcoach->campaigns();

您也可以获取单个活动();

$campaign = $mailcoach->campaign('<campaign-uuid>');

这是创建活动的示例。

$campaign = $this->createCampaign([
   'name' => 'My new campaign',
   'subject' => 'Here is some fantastic content for you',
   'email_list_uuid' => '<email-list-uuid>',
   
   // optionally, you can specify the uuid of a template
   'template_uuid' => '<template-uuid>',
   
   // if that template has field, you can pass the values
   // in the `fields` array. If you use the markdown editor,
   // we'll automatically handle any passed markdown
   'fields' => [
        'title' => 'Content for the title place holder',
        'content' => '# My title',
    ],    
]);

您可以获取活动的属性。

$campaign->name;
$campaign->subject;
// ...

查看 Spatie\MailcoachSdk\Resources\Campaign 的源代码，以了解可用属性列表。

您可以通过更改属性之一并调用 save() 来更新活动。

$campaign->name = 'Campaign';
$campaign->save();

当调用 sendTest() 时，将发送测试邮件。

// sending a test to a single person
$campaign->sendTest('john@example.com');

// sending a test to multiple persons
$campaign->sendTest(['john@example.com', 'jane@example.com']);

通过调用 send()，活动将被发送到您列表中的所有订阅者。

$campaign->send();

可以删除活动。

$campaign->delete();

测试

composer test

更改日志

有关最近更改的更多信息，请参阅更改日志。

贡献

有关详细信息，请参阅贡献指南。

安全漏洞

请查看我们的安全策略如何报告安全漏洞。

致谢

许可证

MIT许可证（MIT）。有关更多信息，请参阅许可证文件。

spatie / mailcoach-sdk-php

维护者

详细信息