- Compatible XF versions
- 2.3
This addon has full bounced email and unsubscribed email handling support using the SparkPost Events API - no mailbox required.
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:
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.
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.
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:
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.
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.
