README

这是一个 Spatie 的 Mailcoach 应用程序的官方 API 扩展。

它提供了一组有限的端点，用于通过 API 管理Mailcoach。它还提供了一些 UI，用于管理您的 API 客户端身份验证和 webhook 管理。

安装

要使用此包，您应首先从 Spatie 购买并安装 Mailcoach 到新的或现有的 Laravel 应用程序中。或者，您也可以安装 Mailcoach 独立应用程序。

完成后，您可以将此包与 Mailcoach 一起安装。

您可以通过 composer 安装此包

composer require leeovery/mailcoach-api

准备数据库

发布迁移...

php artisan vendor:publish  --tag=mailcoach-api-migrations

... & 迁移。

php artisan migrate

添加路由宏

将以下行添加到您的 RouteServiceProvider map 方法中

$apiPrefix = 'api';
$webPrefix = '';
Route::mailcoachApi($apiPrefix, $webPrefix);

传递的参数是默认值，所以如果您对它们满意，则可以省略它们。另一方面，如果您需要更改前缀，可以通过更改传递给宏的内容来实现。

发布视图

php artisan vendor:publish  --tag=mailcoach-api-views

发布配置

php artisan vendor:publish  --tag=mailcoach-api-config

在发布的配置文件中，您可以编辑 web 路由和 api 路由的中介。

您还可以在此文件中设置 webhook 密钥。我建议使用环境变量来设置它，并保持其保密性，因为它可以确保您的 webhook 端点保持安全。

设置身份验证

按照 Passport 指示设置 Laravel Passport 以进行机器到机器身份验证

php artisan passport:client --client

现在您应该能够在 Mailcoach 中看到新的菜单选项，即 API 客户端 & Webhooks。

要允许使用 API 访问，您需要创建一个新的 API 客户端。完成后，您将拥有一个 ClientID（是一个整数）和一个 Client Secret。这两个都将用于通过 API 进行身份验证。

要从您的客户端获取对 API 的实际访问权限，您需要获取一个 access_token。为此，从客户端应用程序中，您需要向 [your-api-url]/api/oauth/token 发送 POST 请求，以下为 post body

grant_type:client_credentials
client_id:{your-client-id}
client_secret:{your-client-secret}

这应在每个 API 会话/请求之前获取，因为它们不会永远有效。

要获取一个示例，您可以在终端中运行以下命令来获取 access_token

curl -I -H ‘Content-Type: application/x-www-form-urlencoded’ -X POST ‘{your-api-url}/api/oauth/token' -d ‘grant_type=client_credentials&client_id={your-client-id}&client_secret={your-client-secret}’

用法

考虑...

此 API 做了一些假设，这些假设非常重要。

最主要的一个是，它认为某个电子邮件的订阅者，无论他们属于哪个列表，都是同一个人。Mailcoach 有一个概念，即每个 Subscriber 属于一个 EmailLst。一个人可以订阅多个列表，但这将导致为他们创建多个 Subscriber 记录。

此包引入了一个 Contact 实体，它将根据电子邮件对 Subscriber 记录进行分组，并将电子邮件、姓名和其他元信息在所有他们的 Subscriber 记录中集中。

示例

考虑用户 lee@example.com 订阅了 2 个列表，并退订了 1 个...

一个对 /contact/lee@example.com 的 GET 请求将导致以下响应数据

{
    "data": {
        "email": "lee@example.com",
        "first_name": "Lee",
        "last_name": "Overy",
        "extra_attributes": {
            "full_name": "Lee Overy"
        },
        "subscribed_to": [
            {
                "list_id": 1,
                "subscription_id": 1,
                "subscribed_at": "2020-02-09T12:31:40.000000Z"
            },
            {
                "list_id": 2,
                "subscription_id": 2,
                "subscribed_at": "2020-02-09T12:31:40.000000Z"
            }
        ],
        "unsubscribed_from": [
            {
                "list_id": 3,
                "subscription_id": 3,
                "subscribed_at": "2020-02-09T12:31:40.000000Z",
                "unsubscribed_at": "2020-02-09T12:31:57.000000Z"
            }
        ]
    }
}

从这个文档中，重要的是要注意，如果你想要在EmailLists中保持相同电子邮件地址的Subscriber记录独立，你可能需要分叉这个包并做一些修改。或者提交一个PR，我们再聊聊 :)

端点

此包提供有限数量的端点，你可以在终端中从应用目录运行php artisan route:list来轻松查看。

但简而言之，它提供以下内容

GET /list

获取所有列表。

GET /list/{listId}

通过列表主键ID获取列表。

GET /contact/{email}

获取联系人

POST /contact

创建联系人并订阅一个或多个列表
表单请求规则仅供参考

[
   'email'        => 'required|email:rfc,dns',
   'list_ids'     => 'required|array',
   'list_ids.*'   => ['required', 'integer', new Exists(EmailList::class, 'id')],
   'attributes'   => 'nullable|array',
   'attributes.*' => 'string', 
]

PATCH /contact

更新联系人的姓名和/或电子邮件
添加/删除额外元信息
添加/删除从1个或多个列表中
从所有列表中取消订阅
重新订阅所有列表
表单请求规则仅供参考

[
  'email'                       => 'sometimes|email:rfc,dns',
  'unsubscribe_from_list_ids'   => 'sometimes|array',
  'unsubscribe_from_list_ids.*' => ['sometimes', 'integer', new Exists(EmailList::class, 'id')],
  'resubscribe_to_list_ids'     => 'sometimes|array',
  'resubscribe_to_list_ids.*'   => ['sometimes', 'integer', new Exists(EmailList::class, 'id')],
  'attributes'                  => 'sometimes|nullable|array',
  'attributes.*'                => 'sometimes|nullable|string',
  'unsubscribe_all'             => 'sometimes|accepted|must_be_different:resubscribe_all',
  'resubscribe_all'             => 'sometimes|accepted|must_be_different:unsubscribe_all',
];

POST /campaign

创建一个带有HTML内容的新活动（建议使用Mailable并调用render来生成HTML）
可以安排在未来发送
省略计划日期将导致活动立即发送
表单请求规则仅供参考

[
   'name'         => ['required', 'alpha_dash', new Unique(Campaign::class, 'name')],
   'subject'      => 'required|string',
   'content'      => 'required|string',
   'list_id'      => ['required', 'integer', new Exists(EmailList::class, 'id')],
   'from_email'   => 'sometimes|email:rfc,dns',
   'from_name'    => 'sometimes|string',
   'scheduled_at' => 'sometimes|nullable|date_format:Y-m-d H:i',
];

Webhooks

我们使用出色的Laravel Webhook Server来提供Webhook支持。

如果你想更改一些默认设置，你可以发布该包的配置文件并进行调整。此包仅使用默认设置，因此你更改的内容将生效。

要接收此包发出的Webhooks，你应该使用匹配的客户端包：Laravel Webhook Client。

熟悉环境

熟悉这个包的最简单方法是查看Webhook界面。创建一个新的Webhook，你将看到它是如何工作的。

基本上，每当发生Mailcoach事件时，我们将拦截它，检查是否为此事件配置了任何Webhook，如果是的话，就继续并触发它们。

这样，你的客户端应用就可以在订阅者取消订阅或标记你发送的电子邮件为垃圾邮件等情况时收到通知。

总的来说，通过API触发的任何操作都不会触发Webhook。例外情况是API通过API发送活动 - 这将触发事件和Webhook。然而，通常更新联系人不会触发 - 除非我遗漏了什么。为了安全起见，在使用API和Webhooks时，编写对潜在反馈循环的认识是明智的。

最后一点

如果你不确定这对你来说是如何工作的，最好的做法是检查代码。

测试

composer test

变更日志

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

贡献

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

安全

如果你发现任何与安全相关的问题，请通过me@leeovery.com发送电子邮件，而不是使用问题跟踪器。

leeovery / mailcoach-api

维护者

详细信息