SilverStripe SparkPost module

Setup

Define in your .env file the following variable

SPARKPOST_API_KEY='YOUR_API_KEY_HERE'

or by defining the api key in your config.yml

LeKoala\SparkPost\SparkPostHelper:
    api_key: "YOUR_API_KEY_HERE"

This module uses a custom client (not the official PHP SDK).

You can also autoconfigure the module with the following environment variables

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

By defining the Api Key, the module will register a new transport that will be used to send all emails.

If you're using the SparkPost EU service you can change the API endpoint

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

Register the new mailer

If you define the SPARKPOST_API_KEY variable, the mailer transport will be automatically registered.

Otherwise, you need to call the following line:

SparkPostHelper::registerTransport();

Admin sender

By default in SilverStripe, emails without a from email will use the Email::admin_email value.

This is not convenient for websites using a value taken from the SiteConfig, as resolved with
SparkPostHelper::resolveDefaultFromEmail.

The SparkPostSwiftTransport can automatically take care of that and replace any admin email
with the set value using the following config flag:

LeKoala\SparkPost\SparkPostHelper:
    override_admin_email: true

Make sure to set this after having processed the sparkpost config.

Check if emails can be used as sender

As a convenience, this library offers an utility SparkPostHelper::isEmailDomainReady to help
you determine if an email is ready to be used as a sender.

Please note that this function makes an api call so you may not want to use this to often. It
is a better to use this on verification screens or as part of a validation workflow.

Subaccounts support

If you use a master api key, but need to limit data access,
you can configure a subaccount id

SPARKPOST_SUBACCOUNT_ID=1234;

or through the YML config.

SparkPost integration

This module create a new admin section that allows you to:

• List all messages events and allow searching them
• Have a settings tab to list and configure sending domains and webhook

NOTE : Make sure that you have a valid api key (not a subaccount key) to access
features related to installation of the webhook through the CMS.

Note that by default the messages are cached (or not) according to config. You
can disable this with the following env key

SPARKPOST_DISABLE_CACHE=true

Setting tags or metadata

By using custom headers you can pass parameters to the api by following the
same principle than the SMTP api.

The main way to pass parameters is to add a json encoded string through the
X-MSYS-API header, but you can also use that Mandrill compatiblity layer.

For full details, look at the documentation

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

Webhooks

From the SparkPost Admin, you can setup a webhook for your website. This webhook
will be called and SparkPostController will take care of handling all events
for you. It is registered under the __sparkpost/ route.

By default, SparkPostController will do nothing. Feel free to add your own
extensions to SparkPostController to define your own rules, like "Send an
email to the admin when a receive a spam complaint".

SparkPostController provides the following extension point for all events:

• onAnyEvent

And the following extensions points depending on the type of the event:

• onEngagementEvent
• onGenerationEvent
• onMessageEvent
• onUnsubscribeEvent

You can also inspect the whole payload and the batch id with

• beforeProcessPayload : to check if a payload has been processed
• afterProcessPayload : to mark the payload has been processed or log information

You can test if your extension is working properly by visiting /__sparkpost/test
if your site is in dev mode. It will load sample data from the API.

Please ensure that the url for the webhook is properly configured if required
by using the following configuration

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

You can also define the following environment variable to log all incoming payload into a given
directory. Make sure the directory exists. It is relative to your base folder.

SPARKPOST_WEBHOOK_LOG_DIR='_incoming'

Please also pay attention to the fact that the webhook is called for ALL events
of your SparkPost account, regardless of the fact of which API key generated the transmission.

To help you overcome this, if a subaccount id is defined, events will be filtered according
to this subaccount.

Preventing spam

Make sure you have properly configured your SPF and DKIM records for your domain.

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

Create a DMARC record

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

Leave provide_plain option to true or provide plain content for your emails

Use Mail Tester to troubleshoot your issues

Inlining styles

Although SparkPost can inline styles for you, it may not work properly for complex
style sheet, such as Foundation Emails. This is why the package pelago\emogrifier
is not required by default and styles are inlined in php to get the best results.

If you want to restore built-in functionnality, use this:

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

Swift Mailer 6

Swift Mailer 6 introduced quite a lot of breaking changes, make sure you are not using any of those:

• added Swift_Transport::ping()
• removed Swift_Mime_HeaderFactory, Swift_Mime_HeaderSet, Swift_Mime_Message, Swift_Mime_MimeEntity,
  and Swift_Mime_ParameterizedHeader interfaces
• removed Swift_MailTransport and Swift_Transport_MailTransport
• removed Swift_Encoding
• removed the Swift_Transport_MailInvoker interface and Swift_Transport_SimpleMailInvoker class
• removed the Swift_SignedMessage class
• removed newInstance() methods everywhere
• methods operating on Date header now use DateTimeImmutable object instead of Unix timestamp;
  Swift_Mime_Headers_DateHeader::getTimestamp()/setTimestamp() renamed to getDateTime()/setDateTime()
• bumped minimum version to PHP 7.0
• removed Swift_Validate and replaced by egulias/email-validator

Compatibility

Tested with SilverStripe 4.9+

For 4.x compatibility, use branch 2

For 3.x compatibility, use branch 1

Maintainer

LeKoala - [email protected]