README

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

以下是一些示例

use Spatie\MailcoachSdk\Facades\Mailcoach;

// 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/laravel-mailcoach-sdk

您必须使用以下命令发布配置文件

php artisan vendor:publish --tag="mailcoach-sdk-config"

这是发布配置文件的内容

return [
    /*
     *  You'll find both the API token and endpoint on Mailcoach'
     *  API tokens screen in the Mailcoach settings.
     */
    'api_token' => env('MAILCOACH_API_TOKEN'),

    'endpoint' => env('MAILCOACH_API_ENDPOINT'),
];

在您的.env文件中，您应添加上述配置文件中的条目。您可以在Mailcoach设置中的API令牌屏幕上找到API令牌和端点。

用法

您可以使用Spatie\MailcoachSdk\Facades\Mailcoach外观进行大多数操作。

处理分页

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

以下是如何显示列表上每个订阅者的电子邮件地址

use Spatie\MailcoachSdk\Facades\Mailcoach;

$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

处理电子邮件列表

以下是如何获取所有电子邮件列表

use Spatie\MailcoachSdk\Facades\Mailcoach;

$emailLists = Mailcoach::emailLists();

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

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

以下是创建电子邮件列表的方法

use Spatie\MailcoachSdk\Facades\Mailcoach;

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()。

use Spatie\MailcoachSdk\Facades\Mailcoach;

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

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

use Spatie\MailcoachSdk\Facades\Mailcoach;

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

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

use Spatie\MailcoachSdk\Facades\Mailcoach;

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

这是创建订阅者的方法。

use Spatie\MailcoachSdk\Facades\Mailcoach;

$subscriber = Mailcoach::createSubscriber(
    emailListUuid: '<email-list-uuid>',
    attributes: [
        'email' => '<email-address>',
        'first_name' => 'John',
        'last_name' => 'Doe',
        'tags' => ['Newsletter'],
    ]);

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

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

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

通过更改其中一个属性并调用 save()，您可以更新订阅者。

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

通过调用这些方法，您可以确认、取消订阅和删除订阅者。

$subscriber->confirm();
$subscriber->unsubscribe();
$subscriber->delete();

处理活动

这是获取所有活动的方法。

use Spatie\MailcoachSdk\Facades\Mailcoach;

$campaigns = Mailcoach::campaigns();

您还可以获取单个活动；

use Spatie\MailcoachSdk\Facades\Mailcoach;

$campaign = Mailcoach::campaign('<campaign-uuid>');

这是创建活动的方法

use Spatie\MailcoachSdk\Facades\Mailcoach;

$campaign = Mailcoach::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 / laravel-mailcoach-sdk

维护者

详情