Additional requirements :
- SparkPost account
- PHP v8.1

Adds a SparkPost mail transport option to have all mails sent via your SparkPost account.

This is the XF v2.3 compatible version of SparkPost Mail Transport for XF 2.2 and has been completely rewritten to support Symfony Mail that is used in XF v2.3

This addon has full bounced email and unsubscribed email handling support using the SparkPost Events API - no mailbox required.

Compatibility

Version 3.x of this addon will only work on XenForo 2.3.x - do not try to install it on an earlier version.


You may upgrade between addon versions once you have upgraded your forum version.

Setup

If you haven't already done so, you will need to configure a sending domain for your forum in your SparkPost account. It is highly recommended that you also set up a default bounce domain.

You will then need to create an API key with the following permissions:

• Events Search: Read-only
• Transmissions: Read/Write

Once you have your API key, change the Email transport method in the Email options page to "SparkPost" and paste your API key into the supplied box.







Configuration

As per the screenshot above - you may configure some transport options when configuring SparkPost.

• Click Tracking turns on click tracking on all links in emails sent
• Open Tracking adds a tracking image to all emails sent to track opens
• Test Mode will append '.sink.sparkpostmail.com' to all recipient email addresses so we can test communication with SparkPost without actually sending any emails to the recipients.

Note that it is highly recommended that you set up a custom tracking domain before enabling click or open tracking.

There is an additional configuration page under the SparkPost Mail option heading:

• Message Events Batch Size allows you to configure how many events the system will attempt to retrieve in each batch. In general you shouldn't need to adjust this from the default.

Testing

You can test the functionality of the addon using the built in XenForo email test system - go to the admin UI > Tools > Test outbound email



Note the email transport class should be \Hampel\Symfony\Mailer\SparkPost\Transport\SparkPostApiTransport - if it isn't, then you haven't installed or activated the addon correctly.

There is also a second test facility which allows you to specify whether to send transaction or non-transactional emails. Go to the admin UI > Tools > Test SparkPost



Turn on the checkbox to send transactional email - turn it off to send non-transactional.

In all cases, you should examine the headers of the emails you receive to verify that it was indeed sent via SparkPost and to validate the presence/absence of the List-Unsubscribe header (the header should be present for non-transactional emails and absent for transactional emails).

Transactional vs Non-transactional Emails

Transactional emails are automated emails sent by a system to communicate with a customer or site user about information relevant to their account or usage of your site. They are typically specific to an individual user and are generally important to the user for the ongoing use of your site.

Examples of transactional emails are:

• account creation and activation emails
• password resets and two-factor authentication
• security and account alerts
• notifications resulting from subscriptions or alert options the user has chosen
• purchase receipts and shipping notifications
• legal and important site notices

Non-transactional emails (also referred to as Commercial Emails) are generally sent to a group of users in bulk (although they may also be personalised), containing promotional or marketing material. Usually only users who have opted in to receive such material from you will receive them.

Examples of non-transactional emails are:

• newsletters
• sales offers
• new product updates
• email designed to increase user engagement and onboarding, etc

The SparkPost website has more information about Transactional vs Commercial emails.

By default, SparkPost marks all emails sent through their API as "non-transactional". This addon changes that behaviour and sets all forum emails to transactional except for:

• Emails sent via the admin UI - Communication > Email users
• Welcome emails

There are two significant differences between transactional and non-transactional emails sent via SparkPost:

1. non-transactional emails have the List-Unsubscribe header added (overrides the header added by XenForo) for one-click unsubscribe requests in some email clients. Transactional emails do not contain this header.
2. there are separate suppression lists for transactional and non-transactional emails. If someone unsubscribes from non-transactional emails, you can still send them important transactional emails like forum subscriptions and password resets. However, if someone unsubscribes or blocks you from transactional emails, you should disable their account, since you will no longer be able to email them about important forum information.

See below for more information on suppression lists.

Bounce and Unsubscribe Handling

The automated bounce and unsubscribe handling in the addon will check for all of the standard hard and soft bounce calls that might be received as a result of sending emails. These bounced messages are intercepted by SparkPost and we can then execute a query to determine what action we need to take as a result.

You do NOT need to configure a "Bounced email address" (unless you don't have a default bounce domain set up) or "Unsubscribe email address" in your email options. Nor do you need to enable the "Automated email handler" or "Enable automated email handler" options - SparkPost does not forward bounced emails or unsubscribe notifications via email - we query their API to determine bounce / unsubscribe information.

Unsubscribe handling is a little more sophisticated than the standard XenForo system - since we differentiate between transactional and non-transactional emails and handle them differently.

Note that if we receive a hard bounce for transactional emails - the users account will be disabled to prevent further emails being sent.

Suppression lists

When SparkPost receives a hard bounce from a sent email or a List-Unsubscribe request, it will place that email address onto a suppression list which means that you can no longer send email to that user. This is in place to protect your sending reputation - since continuing to send email to an invalid or unsubscribed address is a spam indicator which could see you blocked from some mail providers.

The thing to be aware of is that if a users forum account has been disabled due to bounced emails, they will most likely have been added to the SparkPost suppression list as well. If you re-enable their account without changing email addresses, then they may not receive any emails from your site because sending to them is blocked by SparkPost.

If you are sure the email is now valid, you can remove them from the SparkPost suppression list - in the SparkPost admin console - SparkPost.

Just remember that there are two separate lists - one for transactional emails and one for non-transactional emails.

Télécharger V3.0.0 :

Version 3.0.1 bugfix - missing dependencies :
- Some composer dependencies were missing from the 3.0.0 release, causing issues with bounced email handling on some platforms that didn't already have those dependencies installed via other addons. This release fixes the issue.

Télécharger V3.0.1 :

Version 3.0.2 bugfix :
- v3.0.2 addresses a bug in an underlying SparkPost package which resulted in the from header not containing the forum title.

Télécharger V3.0.2 :

Version 3.0.3 bugfix - fix a bug in exception handling in AbstractHttpTransport :
- bugfix - fix a bug in exception handling in AbstractHttpTransport

Télécharger V3.0.3 :

Version 3.0.4 minor bugfix - assert admin permission on tools :
- Minor bugfix to explicitly enforce admin permissions on admincp tools.

Télécharger V3.0.4 :

Version 3.1.1 Updates :

• handle WhatsNewDigest emails in this addon rather than via adapter
• check for WndSparkPost adapter during setup and fail until it is removed - it is incompatible with this version
• change execution order of XF\Admin\Controller\Tools class extension

IMPORTANT: If you have it installed, you must remove the What's New Digest adapter for Sparkpost addon before upgrading SparkPost Mail Transport. The adapter is no longer required and won't work with the latest version of this addon.

Télécharger V3.1.1 :

Version 4.0.0 (2025-09-03) - unreleased​

• drop the usage of sparkpost/sparkpost package because it hasn't been updated in many years - write our own SparkPost
  API wrapper instead
• convert to using XF 2.3 classnames instead of short names
• add CLI commands to fetch message events, process message events and prune message events
• add monolog logging support for most functions
• convert email bounce processor into the MessageEventService
• move to latest version of hampel/symfonymailer-sparkpost to fix bug with ReplyTo headers
• latest composer dependencies

Version 4.0.1 (2026-09-03)​

• bugfix: message event processing failed when the Monolog addon was not installed
• bugfix: SparkPost error details render correctly again on the outbound email test page - the
  message, description and error code fields were empty and the code shown was the HTTP status
  rather than SparkPost's own
• remove a template modification which no longer matched any XenForo 2.3 template
• align the bundled Symfony packages with the versions XenForo itself ships, so that the versions
  Composer resolves are the versions which actually run
• latest composer dependencies, including hampel/symfonymailer-sparkpost 1.1.4

Télécharger V4.0.1 :

Version 5.1.0 (2026-10-14)​

Addon now uses the well-tested hampel/sparkpost and hampel/sparkpost-transport packages for sending and communicating with SparkPost.

• new: sparkpost:config reports what this forum is set up to do and where each value came
  from - the selected transport, whether an API key is set and which host it points at, test mode,
  click and open tracking, the message event page size and the fetch watermark. It never prints the
  key itself, so its output is safe to paste into a support thread
• new: sparkpost:validate proves the forum can actually do it: the container wiring, the
  message event table, the cron entries and the fetch watermark, then one authenticated read from
  SparkPost to confirm the API key is accepted. It sends no mail. --unattended skips that call for
  an unattended check, and --strict exits 2 on warnings rather than 0
• bugfix: with the log level set to debug, every outgoing email was written to the log in full -
  subject, HTML body and text body - which on a busy forum meant every notification and every
  password-reset link. Only a description of the send is logged now. This needs hampel/sparkpost
  1.1.1, which is included
• bugfix: a bounce classification introduced by a later release of hampel/sparkpost no longer
  stops the message event processing job with an UnhandledMatchError. An unrecognised
  classification takes no action against the recipient and is logged as a warning instead
• XenForo 2.4 readiness: every log() this add-on implements now declares a void return type.
  Without it, the add-on would fail fatally on the first email sent once XenForo ships psr/log 3
• the log channel is now requested through Hampel/Monolog 5.x's channel(), falling back to
  newChannel() on 4.x. The channel name is unchanged, so a per-channel log level set in
  config.php keeps working
• the add-on now declares which of its settings are secrets, so a forum running the Admin API can
  report the rest of them
• bugfix: a spelling mistake in the message shown when the incompatible Hampel/WndSparkPost
  adapter is installed

Télécharger V5.1.0 :