README

SparkPost API 邮件发送器 for Yii2

安装

安装此扩展的首选方式是通过 composer。

运行以下命令之一

php composer.phar require --prefer-dist djagya/yii2-sparkpost "*"

或添加

"djagya/yii2-sparkpost": "*"

到您的 composer.json 文件的 require 部分。

设置

要使用 SparkPost，您需要有一个 SparkPost 账户。

他们有一个免费的开发者账户，每月包括高达 15K 条消息，以及一个用于持续开发和测试的沙箱，具有与付费计划相同的功能和性能，无时间限制。

一旦您有了账户，您就需要创建一个 API 密钥。
您可以创建任意数量的 API 密钥，并且为每个网站创建一个密钥是最佳实践。

在等待域名验证期间，为了测试目的，您可以在扩展的配置中启用沙箱模式。

使用方法

要使用此扩展，请在您的应用程序配置中添加以下代码（默认使用 cUrl http 适配器）

return [
    //....
    'components' => [
        'mailer' => [
            'class' => 'djagya\sparkpost\Mailer',
            'apiKey' => 'YOUR_API_KEY',
            'viewPath' => '@common/mail',
            'defaultEmail' => 'sender@example.com', // optional if 'adminEmail' app param is specified or 'useDefaultEmail' is false
            'retryLimit' => 5, // optional
        ],
    ],
];

如果您想禁用消息的默认 "from" 和 "reply to" 电子邮件地址，可以在 Mailer 配置中将 useDefaultEmail 设置为 false，但然后您必须为每条发送的消息指定 "from" 电子邮件地址。

属性 retryLimit 允许 Mailer 进行相对故障转移。如果 Mailer 从 Sparkpost 获取异常，它将尝试发送几次传输，因为 Sparkpost API 有时会失败。当传输尝试次数达到指定的 retryLimit 时 - 最后一次捕获的异常将被抛出。要禁用该行为并尝试仅发送一次传输，可以将 retryLimit 设置为 0。

Http 适配器

您可以使用不同的 http 适配器：cUrl（默认）、guzzle 等。完整列表在这里：可用的适配器。
有关详细信息，请参阅 ivory-http-adapter。

要配置将用于邮件发送器的 http 适配器，您必须在组件配置中指定 httpAdapter 属性，您可以使用字符串、数组或闭包（使用 BaseYii::createObject() 来实例化适配器）

return [
    //....
    'components' => [
        'mailer' => [
            'class' => 'djagya\sparkpost\Mailer',
            'apiKey' => 'YOUR_API_KEY',
            'viewPath' => '@common/mail',
            'httpAdapter' => 'Ivory\HttpAdapter\Guzzle6HttpAdapter', // OR array or closure
        ],
    ],
];

发送电子邮件

然后您可以按照以下方式发送电子邮件

Yii::$app->mailer->compose('contact/html')
    ->setFrom('from@domain.com')
    ->setTo($to)
    ->setSubject($from)
    ->send();

发送电子邮件后，一些属性将填充最后传输的信息

$mailer = Yii::$app->mailer;

$mailer->lastTransmissionId; // string, id of the last transmission
$mailer->lastError; // APIResponseException we got from Sparkpost library with detailed information from the response
$mailer->sentCount; // int, amount of successfuly sent messages
$mailer->rejectedCount; // int, amount of rejected messages

沙箱模式

在您的域名由 Sparkpost 验证之前，您可以通过将 sandbox 选项设置为 true 或直接为消息使用 setSandbox 来使用沙箱模式测试电子邮件发送。
此外，您必须将 "from" 电子邮件地址设置为沙箱 Sparkpost 域。

return [
    //....
    'components' => [
        'mailer' => [
            'class' => 'djagya\sparkpost\Mailer',
            'apiKey' => 'YOUR_API_KEY',
            'sandbox' => true,
            'defaultEmail' => 'test@SPARKPOST_SANDBOX_DOMAIN',
        ],
    ],
];

或者

Yii::$app->mailer->compose('contact/html')
    ->setSandbox(true)
    ->setFrom('test@SPARKPOST_SANDBOX_DOMAIN')
    ->setTo($to)
    ->setSubject($subject)
    ->send();

模板

Sparkpost 模板得到支持。
当您使用模板时，模板的 "from" 和 "subject" 参数将被使用，并覆盖您指定的值。

要设置消息模板及其替换数据（模板上下文），您应该提供一个具有指定 template 键和模板数据的数组，作为第二个参数

Yii::$app->mailer->compose(['template' => 'sparkpost_template_id'], ['template_param' => 'value1', ...])
    ->setTo($to)
    ->send();

或者使用 setTemplateId() 和 setSubstitutionData() 消息方法

Yii::$app->mailer->compose()
    ->setTemplateId('sparkpost_template_id')
    ->setSubstitutionData(['template_param' => 'value1', ...])
    ->setTo($to)
    ->send();

除了可以指定不同的模板数据、元数据和标签，您还可以为To、Cc、Bcc收件人指定这些数据。为此，您需要传递一个地址数组，其中key是电子邮件地址，value是一个包含指定metadata、tags和/或收件人name的数组的数组。

$to = [
    'example@mail.com' => [
        'name' => 'Recipient #1',
        'metadata' => [
            'key' => 'value',
        ],
        'substitution_data' => [
            'template_key' => 'value',
        ],
        'tags' => ['tag1', 'tag2'],
    ],
    // ... other possible addresses
];

Yii::$app->mailer->compose(['template' => 'sparkpost_template_id'], ['template_param' => 'value1', ...])
    ->setTo($to)
    ->send();

单元测试

要运行单元测试，您必须安装Codeception。

运行测试

php /vendor/bin/codecept run

如果您想尝试发送实际的消息，您应该添加APIKEY环境变量（它应该是来自SparkPost的实际API密钥）。
示例

APIKEY=your_api_key php /vendor/bin/codecept run

日志

所有邮件器日志消息都通过特殊的分类sparkpost-mailer由\Yii::error()、\Yii::warning()、\Yii::info()记录。

许可证

yii2-sparkpost的代码根据MIT许可证条款分发（见LICENSE）。

djagya / yii2-sparkpost

维护者

详细信息