larger smaller normal text version of this page
Translations: es

Phplist Documentation » Message functions »

Settings for handling bounces


One of the strengths of phpList is its handling of "bounces".
A bounce is an email message that is returned because it could not be delivered for a number of reasons: The mailbox of the recipient might be full, the email address might no longer be valid or temporarily disabled, the email address might be misspelled, etc. A bounce is not the same as an out-of-office reply. For more info, see this Wikipedia article on bounces.

Note: phpList bounce processing connects to your mail server via a PHP module called IMAP (which should not be confused the IMAP mail protocol). Your PHP server must have this module installed to be able to use the bounce handling features of phpList. If you have a shared hosting account, you should ask your host to include the IMAP module in your PHP installation. Additionally, PHP safe mode must be set to OFF, otherwise automatic bounce processing will not work. See also System requirements


Setting up bounce handling


Message envelope
In the config.php file you can set a special email address called the "message envelope address". The "message_envelope" address is included in the message header as the "Return-Path" address, and will be used to receive bounces. Make sure you create this email account. You can set the $message_envelope in your config.php file. Don't forget to uncomment that line, i.e. remove the # at the start of that line.

$message_envelope = "mybounces@yourdomain.com";

You can check whether this has been setup correctly by displaying the header information of one of your messages, and by looking at its properties and source code. See also RFC 2076 and RFC 3834.
Note that the message envelope address is different from the email address you supply when writing a message, which is the "From:" address, i.e., the one recipients see in the From field of a message. The email address in the "From:" field is the one you tell users to place on their "safe list". It's a good idea to check your "From:" email account for replies from subscribers, because even if you tell them not to reply to messages-- they often will.

Bounce mailbox
So, the "Return-Path" email address is the one that mail system auto-responders (as opposed to user auto-responders such as "out-of-office" replies) will send bounces to if delivery of the message failed or was delayed. It is therefore this account's connection info you need to setup in config.php:

$bounce_mailbox_host       = 'localhost';
$bounce_mailbox_user       = 'mybounces@domain.com';
$bounce_mailbox_password   = 'super-secret';

The format of the values you need to fill in may vary depending on how the server was configured. The "$bounce_mailbox_host" setting might for instance be 'localhost', 'yourpopservername.yourdomain.com', or an IP address. The "$bounce_mailbox_user" setting could be the full email address, just the prefix, or another popusername. Usually the values you would use in your normal email client, will work here too. If you are on a shared hosting account, you can also contact your host. See also this tutorial.

Bounce treshhold
There is one additional setting, a "how many strikes before they're out" rule. This establishes your policy of how many consecutive bounces (bounces in a row) you'll accept before flagging the user's account "unconfirmed". This is that setting:

$bounce_unsubscribe_threshold = 5;

Note: in older versions of phplist (<= v2.10.2) the first "h" of THRESHOLD was missing, so if you are using it please change it to make it work properly.

Other settings
While the above settings are the ones you will usually need to be changed, you may also need to review the defaults for the other bounce handling settings, like the protocol, mailbox port, using cron processing, etc. These settings can be found in:

this block in config.php
# Message envelope. This is the email that system messages come from
# it is useful to make this one where you can process the bounces on
# you will probably get a X-Authentication-Warning in your message
# when using this with sendmail
# NOTE: this is *very* different from the From: line in a message
# to use this feature, uncomment the following line, and change the email address
# to some existing account on your system
# requires PHP version > "4.0.5" and "4.3.1+" without safe_mode
$message_envelope = 'listbounces@yourdomain.com';

# Handling bounces. Check README.bounces for more info
# This can be 'pop' or 'mbox'
$bounce_protocol = 'pop';

# set this to 0, if you set up a cron to download bounces regularly by using the
# commandline option. If this is 0, users cannot run the page from the web
# frontend. Read README.commandline to find out how to set it up on the
# commandline
define ("MANUALLY_PROCESS_BOUNCES",1);

# when the protocol is pop, specify these three
$bounce_mailbox_host = 'localhost';
$bounce_mailbox_user = 'popuser';
$bounce_mailbox_password = 'password';

# the "port" is the remote port of the connection to retrieve the emails
# the default should be fine but if it doesn't work, you can try the second
# one. To do that, add a # before the first line and take off the one before the
# second line

$bounce_mailbox_port = "110/pop3/notls";
#$bounce_mailbox_port = "110/pop3";
#$bounce_mailbox_port = "110/pop3/novalidate-cert";  # Try this to work around "self-cert" email server...
                                                     #   http://www.php.net/manual/en/ref.imap.php


# when the protocol is mbox specify this one
# it needs to be a local file in mbox format, accessible to your webserver user
$bounce_mailbox = '/var/spool/mail/listbounces';

# set this to 0 if you want to keep your messages in the mailbox. this is potentially
# a problem, because bounces will be counted multiple times, so only do this if you are
# testing things.
$bounce_mailbox_purge = 1;

# set this to 0 if you want to keep unprocessed messages in the mailbox. Unprocessed
# messages are messages that could not be matched with a user in the system
# messages are still downloaded into PHPlist, so it is safe to delete them from
# the mailbox and view them in PHPlist
$bounce_mailbox_purge_unprocessed = 1;

# how many bounces in a row need to have occurred for a user to be marked unconfirmed
$bounce_unsubscribe_threshold = 5;


From version 2.11.4
# When only user is unconfirmed when consecutive bounces are over the threshold, 'mark all users
# confirmed' will cause a lot of useless bouncing (email that is, not pogo). It's better to blacklist
# the address so phplist will never try again. Default on.
define('BLACKLIST_EMAIL_ON_BOUNCE', 1);


Related pages

CategoryDocumentation
Page was generated in 0.1773 seconds