Email bounce tracking system
From LimeSurvey Manual
Introduction
The mail bounce tracking system (available in v1.91 or later) is capable of tracking down and marking the emails that were not delivered to the recipients (participants). The system relies on the "mail delivery notification failure report". Therefore, it needs an email address where the emails can be sent to in order to track the bounces . Along with the address of the account, the credentials of the account are also required, with the connection details.
Requirements
The php5-imap module must be installed on your server. You can check if this is the case by looking at the Show PHPinfo button, found on the global settings page of your LimeSurvey installation, under the Overview tab:
Next, look for an imap section, like this. If an imap section is shown, you are good to go:
If you don't have php5-imap installed and you have root access to the server, you can install it following the proceudure specific to your distribution. For example, check this link if you use Debian. Just remember to restart your web server once it is installed (e.g. run "apache/usr/sbin/apache2ctl restart" in terminal).
How it works
The basic idea behind the development of the system was to reduce the manual work and reduce the possible human errors that might arise from manually editing every field.
The basic idea behind this system is that when sending the mail, the mail bounce tracking system automatically adds a survey-id and token-id to the mail header without the notice of the administrator.
These headers (also known as custom headers) are added to each invitation email sent via LimeSurvey to the survey participants.
When the mail is bounced back, the original header along with the Delivery notification header is received. The system then checks for new mails and parses the mails that have these custom headers and mark the wrong e-Mail id in the red font color in the tokens table.
Setting up the system
The system is capable of working at the global level or survey level, thus the settings can be saved accordingly. The global settings can be saved under Global Settings -> Bounce Settings.
The local settings can be entered under the token management of that particular survey.
As you can see in the screenshot above the setting to be used in that particular survey is to be selected. Available options are
- No settings to be used
- Use settings below (survey-specific)
- Use global settings
When sending invitiations or reminders for your survey you have two choices:
1.) Using our mail server
If you are using the LimeSurvey Professional mail server, all your emails will have the sender address noreply@limesurvey.org. However, these emails will have a Reply-to header with your email address. So in case someone tries to reply they will write to you directly.
Although this method is set up very quickly (just enter global settings and set 'LimeSurvey' as your preferred mail type) it has one downside: If an email cannot be transmitted to the email receiver and bounces back, then you won't get any notifications whatsoever. Please don't abuse LimeSurvey for spam or we will have to lock your account. Make sure that you have the general consent of people you want to send invitations to.
2.) Using your own SMTP server
This method has the advantage that you can send all email invitations and reminders using your own sender address and you will get bounced emails back. Most email and hosting providers offer SMTP to send emails. The only thing for you to find out is how to send an email via that SMTP - by figuring out the following details:
Email address (which is allowed to send using that server) SMTP user name (in many cases this is the same as the email address) SMTP host name Password Does your SMTP require an SSL or TLS connection? If yes, also find out which port it is. Then enter the global settings dialog in your LimeSurvey installation and go to the email tab - enter the required data. If your SMTP server is using a special port, then attach it to the host name with a colon. For example, if your host name is 'smtp.server.net' and the port is 143, then write 'smtp.server.net:143' as host name. For security reasons we currently only allow the following ports numbers: 110, 143, 587, 993 and 995.
After you save the new settings make sure that you enter that same valid email address in the survey settings of your survey.
Now it should all be running fine.
A note to email server administrators: LimeSurvey will initialize the SMTP connection from the IP address of your LimeSurvey installation. Just ping the URL of the LimeSurvey installation to find out which one it is. In case you have your SMTP server locked down you will need to add this IP address as an exception to your SMTP configuration/firewall.
Starting Bounce Processing in v2.5
In version 2.50+, once the bounce processing system has been set you can start Bounce Processing by accessing the appropriate menu choice option on the "Invitations & reminders" button of the "Survey participants" menu as illustrated below.
The "Survey participants" menu can be reached by clicking the "Survey Participants" button either in the left hand menu or the top menu of the Survey homepage.
After selecting this option a progress indicator will be displayed during processing, followed by a final processing status summary.
Note: some releases of v2.50+ do not correctly display this menu choice and the issue was fixed in build 160714 released on July 14, 2016
Starting Bounce Processing in earlier versions
Once the settings have been set you can start the bounce processing by clicking on the bounce processing icon in the Token browser toolbar as shown below.
After clicking the icon you will be presented with a popup which shows a progress meter.
Wait for it to complete. Once complete the result of the scan will be shown and after a refresh of the browse responses page (you might have to do that manually) all the entries whose invitation are bounced their e-mail address are marked in red font. Also their "Email status" is chanced from "OK" to "bounced".
