README

此模块提供通过Mailgun API发送电子邮件并使用Mailgun的webhook功能存储与消息相关事件的功能。

要求

silverstripe/framework ^4
Symbiote的Queued Jobs模块
Mailgun PHP SDK ^3, kriswallsmith/buzz, nyholm/psr7

Mailgun配置

您需要

一个Mailgun账户
至少一个非沙箱Mailgun邮寄域（验证最佳）在您选择的区域
一个Mailgun API密钥或一个针对相关邮寄域的Mailgun域发送密钥（后者推荐使用）
MailgunEmail和MailgunMailer已在您的项目中配置（见下文）

安装

composer require nswdpc/silverstripe-mailgun-sync

配置

Mailgun账户

您的Mailgun域和账户的配置超出了本文件的范畴，但操作简单。

您应验证您的域以避免消息投递问题。最佳起点是验证域。

MXToolBox.com是一个有用的工具，可以检查您的邮寄域是否具有有效的DMARC记录。

模块

将以下内容添加到您的项目的yaml配置中

---
Name: local-mailgunsync-config
After:
  - '#mailgunsync'
---
# API config
NSWDPC\Messaging\Mailgun\Connector\Base:
  # your Mailgun mailing domain
  api_domain: 'configured.mailgun.domain'
  # your API key or Domain Sending Key
  api_key: 'xxxx'
  # the endpoint region, if you use EU set this value to 'API_ENDPOINT_EU'
  # for the default region, leave empty
  api_endpoint_region: ''
  # this setting triggers o:testmode='yes' in messages
  api_testmode: true|false
  # You will probably want this as true, when false some clients will show 'Sent on behalf of' text
  always_set_sender: true
  # set this to override the From header, this is useful if your application sends out mail from anyone (see DMARC below)
  always_from: 'someone@example.com'
  # Whether to send via a job - see below
  send_via_job: 'yes|no|when-attachments'
  # When set, messages with no 'To' header are delivered here.
  default_recipient: ''
  # grab this from your Mailgun account control panel
  webhook_signing_key: ''
  # whether you want to store webhook requests
  webhooks_enabled: true|false
  # the current or new filter variable (see webhooks documentation in ./docs)
  webhook_filter_variable: ''
  # the previous one, to allow variable rotation
  webhook_previous_filter_variable: ''
---
# Configure the mailer
Name: local-mailer
After:
  # Override core email configuration
  - '#emailconfig'
---
# Send messages via the MailgunMailer
SilverStripe\Core\Injector\Injector:
  SilverStripe\Control\Email\Email:
    class: 'NSWDPC\Messaging\Mailgun\MailgunEmail'  
  SilverStripe\Control\Email\Mailer:
    class: 'NSWDPC\Messaging\Mailgun\MailgunMailer'

请记住在配置更改后刷新配置。

查看详细配置，包括项目标签

发送

Mailer

有关此内容的良好示例，请查看MailgunSyncTest类。消息使用默认的Silverstripe Email API发送

use SilverStripe\Control\Email\Email;

$email = Email::create();
$email->setFrom($from);
$email->setTo($to);
$email->setSubject($subject);

要添加Mailgun使用的自定义参数，请调用setCustomParameters()

// variables
$variables = [
    'test' => 'true',
    'foo' => 'bar',
];

//options
$options = [
    'testmode' => 'yes',
    'tag' => ['tag1','tag2','tag4'],
    'tracking' => 'yes',
    'require-tls' => 'yes'
];

// headers
$headers = [
    'X-Test-Header' => 'testing'
];

$recipient_variables = [
    'someone@example.com' => ["unique_id" => "testing_123"]
];

$args = [
    'options' => $options,
    'variables' => $variables,
    'headers' => $headers,
    'recipient-variables' => $recipient_variables
];

$email->setCustomParameters($args)

其中$args是一个包含您自定义参数的数组。多次调用setCustomParameters()将覆盖之前的参数。

发送消息

$response = $email->send();

响应将是一个Mailgun消息-id，或者如果您是通过排队作业发送，则是一个Symbiote\QueuedJobs\DataObjects\QueuedJobDescriptor实例。

通过API连接器

您可以直接通过API连接器发送，该连接器根据配置处理客户端设置等。有关此内容的良好示例，请查看MailgunMailer类

use NSWDPC\Messaging\Mailgun\Connector\Message;

//set parameters
$parameters = [
    'to' => ...,
    'from' => ...,
    'o:tag' => ['tag1','tag2']
    // etc
];
$connector = Message::create();
$response = $connector->send($parameters);

响应将是一个Mailgun消息-id，或者如果您是通过排队作业发送，则是一个Symbiote\QueuedJobs\DataObjects\QueuedJobDescriptor实例。

直接发送到Mailgun PHP SDK

如果您喜欢，您可以通过Mailgun PHP SDK发送消息并与Mailgun API交互

use Mailgun\Mailgun;

$client = Mailgun::create($api_key);
// set things up then send
$response = $client->messages()->send($domain, $parameters);

如果成功，响应将是一个Mailgun\Model\Message\SendResponse实例。

有关示例，请参阅Mailgun PHP SDK文档

排队作业

此模块使用Queued Jobs模块在以后的时间发送电子邮件。

这样，涉及发送电子邮件的网站请求就不会因为API问题而受阻。

SendJob

这是一个排队作业，可以用于根据send_via_job配置值发送电子邮件-

'yes' - 总是
'when-attachments' - 只有当存在附件时，或
'no' - 从不（在这种情况下，消息永远不会通过排队作业发送）

消息被传递到这个队列作业，该作业配置为在一分钟后发送。一旦投递，消息参数将被清除以减少大消息占用的空间。

在API或其他一般错误发生时，此作业立即标记为“损坏”。请阅读队列作业健康检查文档以获取有关损坏作业报告的协助。

TruncateJob

使用此作业清除旧版的MailgunEvent webhook记录。如果您不使用webhook来存储事件，则此作业可以保持未使用。

RequeueJob

使用此作业重新启动因API或连接问题而偶尔发生的损坏的SendJob实例。

此作业将

获取所有损坏的SendJob作业描述符记录
将它们的状况、处理次数和工作者值重置为默认初始值
将它们设置为在一分钟后开始
保存记录

在下一次队列运行时，这些作业将尝试再次发送。

手动重新提交

可以从Mailgun控制面板重新发送消息。这取决于您在Mailgun中设置的相关邮件域的消息保留设置。

DMARC考虑事项

在发送电子邮件时，明智地考虑如何维护您邮件域（以及IP）的质量。

如果您的邮件域是“mg.example.com”，并且您发送“From: someone@example.net”，则DMARC规则很可能会在接收邮件服务器上启动，并且您的消息将被隔离或拒绝（除非example.net指定example.com为允许的发送者）。相反，在您的消息中使用“From: someone@mg.example.com”或“From: someone@example.com”。

您的“Reply-To”头可以是任何有效的地址。

有关DMARC、SPF和DKIM重要性的更多信息，请参阅dmarc.org

测试

单元测试：./tests。测试使用TestMessage连接器。

使用sandbox/testmode发送电子邮件

对于验收测试，您可以使用Mailgun沙盒域和API测试模式的组合。

沙盒域：将配置中的api_domain值设置为Mailgun提供的沙盒域。请记住，在Mailgun控制面板的沙盒域设置中列出已批准的接收者。
测试模式：将api_testmode值设置为true。在测试模式下，Mailgun接受但不投递消息。

1.0版本中的破坏性更改

版本1删除了未使用的功能，以减少此模块的复杂性。

核心功能现在是

通过Silverstripe的标准电子邮件过程发送消息，并添加了Mailgun选项
直接通过API发送消息
通过专用控制器处理来自Mailgun的webhook请求

事件同步现在由webhooks控制器处理

许可证

BSD-3-Clause

请参阅LICENSE

维护者

dpcdigital@NSWDPC:~$

错误跟踪器

我们欢迎对此项目的Github Issue跟踪器提交错误报告、pull请求和功能请求。

在打开新问题之前，请先查看行为准则。

安全

如果您在此模块中发现安全漏洞，请首先通过digital[@]dpc.nsw.gov.au发送电子邮件，详细说明您的发现。

开发和贡献

如果您想为此模块做出贡献，请确保您提出一个拉取请求并与模块维护者进行讨论。

在完成拉取请求之前，请查阅行为准则。

nswdpc / silverstripe-mailgun-sync

维护者

详细信息