PHPackages lekoala/silverstripe-sparkpost - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Mail & Notifications](/categories/mail) 4. / 5. lekoala/silverstripe-sparkpost ActiveSilverstripe-module[Mail & Notifications](/categories/mail) lekoala/silverstripe-sparkpost ============================== SparkPost integration for SilverStripe CMS 3.1.4(1y ago)78.6k↓50%11MITPHPPHP >=8.1CI passing Since Aug 20Pushed 1y ago2 watchersCompare [ Source](https://github.com/lekoala/silverstripe-sparkpost)[ Packagist](https://packagist.org/packages/lekoala/silverstripe-sparkpost)[ GitHub Sponsors](https://github.com/lekoala)[ RSS](/packages/lekoala-silverstripe-sparkpost/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (10)Dependencies (10)Versions (30)Used By (0) SilverStripe SparkPost module ============================= [](#silverstripe-sparkpost-module) [![Build Status](https://github.com/lekoala/silverstripe-sparkpost/actions/workflows/ci.yml/badge.svg)](https://github.com/lekoala/silverstripe-sparkpost/actions/workflows/ci.yml/badge.svg)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/f717cfcd9472b5c54715f3ecae0a81792b98cfcc26e0e95f3c2af842a9f3f32b/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f6c656b6f616c612f73696c7665727374726970652d737061726b706f73742f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/lekoala/silverstripe-sparkpost/?branch=master)[![Code Coverage](https://camo.githubusercontent.com/595113679e57364be6d8408d706bcfb022e9d1b7b4ac2d56f3970f78bdeae2d9/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f6c656b6f616c612f73696c7665727374726970652d737061726b706f73742f6261646765732f636f7665726167652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/lekoala/silverstripe-sparkpost/?branch=master)[![Build Status](https://camo.githubusercontent.com/b45395cb0c7bfa30c21464ff532052866b8f9415d5e24c135d7d989e881e773c/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f6c656b6f616c612f73696c7665727374726970652d737061726b706f73742f6261646765732f6275696c642e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/lekoala/silverstripe-sparkpost/build-status/master)[![codecov.io](https://camo.githubusercontent.com/b7091c2c72c59796ccff0b2d74584ef26d78c1d9a60b7adc9c69c29124d1a9b7/68747470733a2f2f636f6465636f762e696f2f6769746875622f6c656b6f616c612f73696c7665727374726970652d737061726b706f73742f636f7665726167652e7376673f6272616e63683d6d6173746572)](https://codecov.io/github/lekoala/silverstripe-sparkpost?branch=master) [![Latest Stable Version](https://camo.githubusercontent.com/1454bafdc532c3e0856936a1c46c52ee8a956d1163369b54f664d56123d63d22/68747470733a2f2f706f7365722e707567782e6f72672f6c656b6f616c612f73696c7665727374726970652d737061726b706f73742f76657273696f6e)](https://packagist.org/packages/lekoala/silverstripe-sparkpost)[![Latest Unstable Version](https://camo.githubusercontent.com/72faaee3e876f8359c0c92e7c5a10cdfae1f7ab8712317e0bfe1623c3aaaebeb/68747470733a2f2f706f7365722e707567782e6f72672f6c656b6f616c612f73696c7665727374726970652d737061726b706f73742f762f756e737461626c65)](//packagist.org/packages/lekoala/silverstripe-sparkpost)[![Total Downloads](https://camo.githubusercontent.com/d06a10c9b296aa282a92c6413b35f5890306ea16b213d8d6e898adc97cb3e144/68747470733a2f2f706f7365722e707567782e6f72672f6c656b6f616c612f73696c7665727374726970652d737061726b706f73742f646f776e6c6f616473)](https://packagist.org/packages/lekoala/silverstripe-sparkpost)[![License](https://camo.githubusercontent.com/5c1bd64431fbd1e677671e913b4be0c8acfe0cfa49b3f1073405d8a7b6aa22e6/68747470733a2f2f706f7365722e707567782e6f72672f6c656b6f616c612f73696c7665727374726970652d737061726b706f73742f6c6963656e7365)](https://packagist.org/packages/lekoala/silverstripe-sparkpost)[![Monthly Downloads](https://camo.githubusercontent.com/9f0171c032ef6507be8712cc081a69b9b2ae4f0b7a59eca8588aceb1920957f2/68747470733a2f2f706f7365722e707567782e6f72672f6c656b6f616c612f73696c7665727374726970652d737061726b706f73742f642f6d6f6e74686c79)](https://packagist.org/packages/lekoala/silverstripe-sparkpost)[![Daily Downloads](https://camo.githubusercontent.com/5f16a022255c3cc60de2d82ee150af2adfaf5c9f711b1248172ef6b318ff4af7/68747470733a2f2f706f7365722e707567782e6f72672f6c656b6f616c612f73696c7665727374726970652d737061726b706f73742f642f6461696c79)](https://packagist.org/packages/lekoala/silverstripe-sparkpost) Setup ----- [](#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 ----------------------- [](#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 ------------ [](#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 SparkPostApiTransport 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 ------------------------------------- [](#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 ------------------- [](#subaccounts-support) If you use a master api key, but need to [limit data access](https://developers.sparkpost.com/api/#/introduction/subaccounts), you can configure a subaccount id ``` SPARKPOST_SUBACCOUNT_ID=1234; ``` or through the YML config. SparkPost integration --------------------- [](#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 ------------------------ [](#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](https://developers.sparkpost.com/api/smtp/) ``` $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 -------- [](#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 --------------- [](#preventing-spam) Make sure you have properly configured your [SPF](https://tools.sparkpost.com/spf/builder) and DKIM records for your domain. ``` mydomain.com TXT "v=spf1 include:myauthorizeddomain.com include:sparkpostmail.com ~all” ``` Create a [DMARC record](https://www.zerobounce.net/services/dmarc-generator.html). See [why this is important](https://support.google.com/a/answer/2466563?hl=en). ``` _dmarc.mydomain.com. 3600 IN TXT "v=DMARC1; p=quarantine; sp=quarantine; rf=afrf; pct=100; ri=86400;" ``` Leave provide\_plain option to true or provide plain content for your emails Use [Mail Tester](http://www.mail-tester.com/) to troubleshoot your issues Inlining styles --------------- [](#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 ``` Migration from Swift Mailer =========================== [](#migration-from-swift-mailer) SilverStripe 5 replaced swift mailer by symfony/mailer Make sure to read the docs [https://docs.silverstripe.org/en/5/developer\_guides/email/](https://docs.silverstripe.org/en/5/developer_guides/email/) Compatibility ------------- [](#compatibility) Tested with SilverStripe 5+ For 4.9+ compatibility, use branch 3 For 4.x compatibility, use branch 2 For 3.x compatibility, use branch 1 Maintainer ---------- [](#maintainer) LeKoala - ### Health Score 49 — FairBetter than 95% of packages Maintenance46 Moderate activity, may be stable Popularity33 Limited adoption so far Community18 Small or concentrated contributor base Maturity82 Battle-tested with a long release history Bus Factor1 Top contributor holds 95.6% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~86 days Recently: every ~94 days Total 29 Last Release 403d ago Major Versions 0.3 → 1.0.72021-02-19 1.0.8 → 2.x-dev2021-03-10 0.3.1 → 2.0.02021-10-05 2.0.2 → 3.x-dev2022-09-14 2.0.3 → 3.0.02023-07-26 PHP version history (5 changes)1.0.0PHP >=5.6 0.1PHP >=5.4.8 2.x-devPHP >7.2 3.x-devPHP ^7.4 || ^8.0 3.0.0PHP >=8.1 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/250762?v=4)[Thomas Portelange](/maintainers/lekoala)[@lekoala](https://github.com/lekoala) --- Top Contributors [![lekoala](https://avatars.githubusercontent.com/u/250762?v=4)](https://github.com/lekoala "lekoala (197 commits)")[![martinduparc](https://avatars.githubusercontent.com/u/839534?v=4)](https://github.com/martinduparc "martinduparc (4 commits)")[![ec8or](https://avatars.githubusercontent.com/u/1678184?v=4)](https://github.com/ec8or "ec8or (2 commits)")[![a2nt](https://avatars.githubusercontent.com/u/672794?v=4)](https://github.com/a2nt "a2nt (1 commits)")[![edwilde](https://avatars.githubusercontent.com/u/415374?v=4)](https://github.com/edwilde "edwilde (1 commits)")[![sasky](https://avatars.githubusercontent.com/u/1792215?v=4)](https://github.com/sasky "sasky (1 commits)") --- Tags emailsilverstripesilverstripe-4silverstripe-5silverstripe-modulesparkpostsilverstripecmsmodulesparkpost ### Code Quality TestsPHPUnit Code StylePHP\_CodeSniffer ### Embed Badge ![Health badge](/badges/lekoala-silverstripe-sparkpost/health.svg) ``` [![Health](https://phpackages.com/badges/lekoala-silverstripe-sparkpost/health.svg)](https://phpackages.com/packages/lekoala-silverstripe-sparkpost) ``` ### Alternatives [lekoala/silverstripe-mandrill Adds mandrill in the SilverStripe CMS 1827.3k](/packages/lekoala-silverstripe-mandrill)[lekoala/silverstripe-cms-actions Add actions to your models in SilverStripe 39279.9k22](/packages/lekoala-silverstripe-cms-actions)[friendsofsilverstripe/backendmessages DRY way to create message boxes in SilverStripe backend. 1015.4k2](/packages/friendsofsilverstripe-backendmessages) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)