Handling bounces with phpList

In this article we'll discuss how phpList handles bounce backs. A bounce back can happen when one of the users you attempt to send a message to does not receive the message, and it "bounces back" to you with an explanation of why.

One of the great things of managing your mailings via phpList is that it can handle bounce back processing for you to help keep tabs on what users might have changed their email address, or are having other issues receiving your mailings.

Configure phpList to handle bounces

Before phpList is able to handle bounce back messages for you, first there are a few options that you need to change in your config file. Using the steps below we'll walk you though these.

1. Open up the File Manager Code Editor in cPanel.
2. From the left, expand your /public_html/list/config/ directory.
3. Right click on your config.php file, then click on Code Edit

   If the code editor encoding check pop-up displays, go ahead and click on Edit

4. You'll want to use Ctrl-F to bring up the Code Editor's find function. You need to look for message_envelope. It should be around line 71 and the entire section of code we'll be taking a look at and modifying is the following:

   # $message_envelope = 'listbounces@yourdomain';
   # 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';

   We need to un-comment the $message_envelope line by removing the # symbol from the beginning of the line. Then you need to type in the email address you'd like phpList to send mail from, note that this is different than what you type in the From section when sending a message.

   If you set your from address to no-reply@PrimaryDomain.com for instance, if a user tries to hit reply that's where they'll be sending to. But if you have your message_envelope set to listbounces@PrimaryDomain.com this is the address used for bounce backs.

   Without setting this your mail will be sent out from your actual cPanel user, so userna5@ecbiz103.inmotionhosting.com or something similar. You would be able to directly check the bounce backs by logging into webmail with your main cPanel account, but to have phpList handle bounce backs for you, you'll want to create a separate email address for this.

   You also need to update the bounce_mailbox_user, and bounce_mailbox_password sections with your valid email credential as well.

   When you're done making these modifications click on Save Changes up in the top right of the Code Editor.

   When you're done editing, the config file should look similar to this:

   $message_envelope = 'listbounces@PrimaryDomain.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 = 'listbounces@PrimaryDomain.com';
   $bounce_mailbox_password = 'MyPa$$W0rd';

 

Process bounces in phpList

Following the steps below, you can have phpList connect to your listbounces@PrimaryDomain.com email account, and retreive any bounce backs that have occurred from your recent mailings.

1. Login to your phpList admin dashboard.
2. From the right hand menu, click on process bounces.
3. In this case we can see that we've had 1 user that had a bounce back. Go ahead and click on view bounces from the right hand menu to further inspect this.
4. We can see that in our last 2 mailings, the same user 630 had their message bounce back. Go ahead and click on show beside one of the bounce backs to view the full details.
5. We can see here that the user that bounced was webmastr@PrimaryDomain.com, looks like there might be a misspelling there. Further down in the body section of the bounce back, we can see that this is the case as their mail server is stating No Such User Here.

   So we are going to check Delete user, and then click on Do the above to remove the user from our list so it doesn't keep on bouncing back.

You should now understand how to configure phpList so that it can handle email bounce backs for you, and also how to process those bounces so that you can figure out why certain user's messages are bouncing back. If you're interested in further details on email bounce backs you can check out our article on why does email bounce, bounceback, or error?