README

安装

在您的 .env 文件中定义以下变量

SPARKPOST_API_KEY='YOUR_API_KEY_HERE'

或者通过在您的 config.yml 中定义API密钥

LeKoala\SparkPost\SparkPostHelper:
    api_key: "YOUR_API_KEY_HERE"

此模块使用自定义客户端（不是官方的PHP SDK）。

您还可以使用以下环境变量自动配置模块

# Will log emails in the temp folders
SPARKPOST_ENABLE_LOGGING=true
# Will disable sending (useful in development)
SPARKPOST_SENDING_DISABLED=true

通过定义API密钥，模块将注册一个新的传输方式，用于发送所有电子邮件。

如果您使用SparkPost EU服务，您可以更改API端点

# Will use https://api.eu.sparkpost.com/api/v1
SPARKPOST_EU=true

注册新的邮件发送器

如果定义了SPARKPOST_API_KEY变量，邮件发送器传输将自动注册。

否则，您需要调用以下行

SparkPostHelper::registerTransport();

管理员发送者

在SilverStripe中默认情况下，没有“发件人电子邮件”的电子邮件将使用Email::admin_email的值。

这对于使用SiteConfig中取值的网站来说不方便，可以通过SparkPostHelper::resolveDefaultFromEmail来处理。

SparkPostApiTransport可以自动处理此问题，并使用以下配置标志将任何管理员电子邮件替换为设置的值

LeKoala\SparkPost\SparkPostHelper:
    override_admin_email: true

请确保在处理sparkpost配置后设置此值。

检查电子邮件是否可以作为发送者使用

为了方便起见，此库提供了一个实用工具SparkPostHelper::isEmailDomainReady，帮助您确定电子邮件是否可以用于作为发送者。

请注意，此函数会进行API调用，因此您可能不想经常使用此功能。更好的做法是在验证屏幕或作为验证工作流的一部分使用它。

子账户支持

如果您使用主API密钥，但需要限制数据访问，您可以配置子账户ID

SPARKPOST_SUBACCOUNT_ID=1234;

或通过YML配置。

SparkPost集成

此模块创建一个新的管理员部分，允许您

列出所有消息事件，并允许搜索它们
拥有一个设置选项卡，用于列出和配置发送域和webhook

注意：请确保您有一个有效的API密钥（不是子账户密钥）以访问通过CMS安装webhook的相关功能。

请注意，默认情况下，消息根据配置进行缓存（或不清缓存）。您可以使用以下环境键禁用此功能

SPARKPOST_DISABLE_CACHE=true

设置标签或元数据

通过使用自定义头，您可以通过遵循与SMTP API相同的原则将参数传递给API。

传递参数的主要方式是通过X-MSYS-API头添加json编码的字符串，但您也可以使用Mandrill兼容性层。

有关详细信息，请参阅文档

$email = new Email();
$email->setSubject($sellerTitle . ' - Invoice - ' . $date);
$email->setBody($body);
// Through Mandrill compat layer
$email->getHeaders()->addTextHeader('X-MC-Metadata', json_encode(['RecordID' => $this->ID]));
// Or use M-SYS header
$email->getHeaders()->addTextHeader('X-MSYS-API', json_encode(['metadata' => ['RecordID' => $this->ID]]));

Webhooks

从SparkPost管理员那里，您可以设置您网站的webhook。此webhook将被调用，SparkPostController将负责处理所有事件。它注册在__sparkpost/路由下。

默认情况下，SparkPostController不会做任何事情。您可以自由地向SparkPostController添加自己的扩展来定义自己的规则，例如“当收到垃圾邮件投诉时向管理员发送电子邮件”。

SparkPostController为所有事件提供以下扩展点

onAnyEvent

以及根据事件类型的不同，以下扩展点

onEngagementEvent
onGenerationEvent
onMessageEvent
onUnsubscribeEvent

您还可以使用以下命令来检查整个有效载荷和批次ID：

beforeProcessPayload：检查有效载荷是否已被处理
afterProcessPayload：标记有效载荷已被处理或记录信息

如果您的网站处于开发模式，您可以通过访问/__sparkpost/test来测试您的扩展是否正常工作。它将从API加载示例数据。

请确保在需要的情况下，使用以下配置正确配置webhook的URL：

LeKoala\SparkPost\SparkPostAdmin:
    webhook_base_url: "https://my.domain.com/"

您还可以定义以下环境变量，将所有传入的有效载荷记录到指定的目录。请确保该目录存在。它相对于您的基本文件夹。

SPARKPOST_WEBHOOK_LOG_DIR='_incoming'

请注意，无论哪个API密钥生成了传输，webhook都会调用您的SparkPost账户的所有事件。

为了帮助您解决这个问题，如果定义了子账户ID，事件将根据此子账户进行筛选。

防止垃圾邮件

请确保您已正确配置您域的SPF和DKIM记录。

mydomain.com   TXT   "v=spf1 include:myauthorizeddomain.com include:sparkpostmail.com ~all”

创建一个DMARC记录。请参阅为什么这很重要。

_dmarc.mydomain.com. 3600 IN TXT "v=DMARC1; p=quarantine; sp=quarantine; rf=afrf; pct=100; ri=86400;"

将provide_plain选项设置为true或为您的电子邮件提供纯文本内容

使用Mail Tester来排查问题

内联样式

尽管SparkPost可以为您内联样式，但对于复杂的样式表（如Foundation电子邮件），它可能无法正常工作。这就是为什么pelago\emogrifier包默认不要求，并且将样式内联到php中，以获得最佳结果。

如果您想恢复内置功能，请使用此

LeKoala\SparkPost\SparkPostHelper:
    inline_styles: false
    default_params:
    inlineCss: true

从Swift Mailer迁移

SilverStripe 5用symfony/mailer替换了swift mailer

请务必阅读以下文档：https://docs.silverstripe.org/en/5/developer_guides/email/ https://symfony.ac.cn/doc/current/mailer.html

兼容性

与SilverStripe 5+进行了测试

对于4.9+兼容性，请使用分支3

对于4.x兼容性，请使用分支2

对于3.x兼容性，请使用分支1

维护者

LeKoala - thomas@lekoala.be

lekoala / silverstripe-sparkpost

维护者

详细信息