- Compatible XF 2.x versions
- Additional requirements
- SparkPost account
Note that v1.x of this addon is not compatible with XenForo v2.2 - immediately after upgrading to XF v2.2, you must install v2.x of this addon available here: https://xenforo.com/community/resources/sparkpost-mail-transport-for-xf-2-2.7990/
This addon has full bounced email and unsubscribed email handling support using the SparkPost Events API - no mailbox required.
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
- (Note, current version instructs you to allow
Send via SMTPAPI permission, but this is not required - these instructions will be removed in a future release).
There are several options you can configure for mail sending and event processing in the SparkPost Mail option screen:
- 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
- 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.
- 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.
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
\SwiftSparkPost\Transport - 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
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
Examples of non-transactional emails are:
- sales offers
- new product updates
- email designed to increase user engagement and onboarding, etc
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
- non-transactional emails have the
List-Unsubscribeheader added (overrides the header added by XenForo) for one-click unsubscribe requests in some email clients. Transactional emails do not contain this header.
- 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.
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.
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 - https://app.sparkpost.com/lists/suppressions.
Just remember that there are two separate lists - one for transactional emails and one for non-transactional emails.