Handling email bounces
Sometimes an email sent from FixMyStreet bounces, perhaps because the contact
address for the responsible body is no longer correct. In order for your site
administrator to notice this, you can configure your system to use the
Emails sent to a body when a report is created use something called VERP. Basically this means that if the email bounces, it will be returned to a unique address which includes the report ID, so we can figure out which report needs to be re-sent and which contact address needs to be updated. Alerts use VERP return paths as well, so we can unsubscribe an email address from further alerts.
All email sent to one of these VERP addresses should be handled by the
handlemail script. In addition to this,
handlemail can also handle email
sent to the
The list below describes what
handlemail will do with these emails.
If an actual email (not a bounce) to the DO-NOT-REPLY address:
- If it looks like an out-of-office message, do nothing.
- Send an automatic reply (as a bounce) back to that email saying it is an
unmonitored account (using the
If an actual email (not a bounce) to a VERP address (report submission/alert email):
- If a reply to an alert email and not out-of-office, forward to the
contact email (defaults to
- If a reply to a report email, forward on to the report creator
- If a reply to an alert email and not out-of-office, forward to the contact email (defaults to
If a bounce message to the DO-NOT-REPLY address, ignore it.
If a bounce message to a VERP address:
- If it looks like a permanent bounce (5xx error but not 5.2.2 mailbox full), unsubscribe the alert (alert bounce), or forward on to the contact email (report bounce).
- Otherwise, if it looks like an out-of-office, treat as an actual email (step 2)
- Or if unparseable, forward on to the contact email.
- Otherwise, ignore the bounce.
handlemail script should be run by the same user that runs the FixMyStreet
web service (typically user fms). To configure this, add a line like this to
that user’s .forward file:
The .forward file should be created in the fms user’s home directory. Include
the quotes (
") and leading pipe (
|) character, which specify that the email
should be handled by a program.
Just make sure to set the path to where you have your clone of the fixmystreet repository. You can also specify a cobrand:
The reply-autoresponse template used for emails sent to the DO-NOT-REPLY address will then use the template for that cobrand.
CONTACT_EMAIL as its contact email, but you can
override this by specifying an email in the command line with the
If the fms user is running cron jobs, error messages from those jobs are
typically sent to the fms user. To avoid sending those to
might want to update the crontab for the fms user by adding a
directive, such as:
Finally, you’ll need to make sure that email sent to the VERP addresses and to the DO-NOT-REPLY address is routed to the fms user. This will be different depending on how you’ve configured your email server, but if you’re using Postfix you can do this with a virtual alias table.
Postfix example configuration
In your main.cf (typically /etc/postfix/main.cf), add a regexp table to the virtual_alias_map setting:
virtual_alias_maps = regexp:/etc/postfix/virtual.regexp
Then create the virtual.regexp file and add a rule for routing any email starting with fms- to the fms user:
Before this file can be used by postfix it needs to be compiled:
The Postfix service needs to be restarted since main.cf was modified.
Finally, set the
DO_NOT_REPLY_EMAIL setting in conf/general.yml to
fms-DO-NOT-REPLY@\<yourdomain\> so those emails also match the rule.