Distro Index Owner:
Home Page:
Last updated:
zope plone notification newsletter




Detect bouncing messages from an IMAP folder and allow further processing

eea.bounce - a bouncing subscribers handler

This software gives you a command line utility that can connect to an IMAP mailbox, detect the bouncing messages in that folder and then make a call to a webserver, informing that web application of the subscribers found to be bouncing.

Execution flow

When started, this command line will do the following:

  1. read its list of command line options
  2. connect to the web service to receive an extra list of parameters
  3. connect to the IMAP server and download and bounce detect all messages
  4. move the messages found to be bouncing into the indicated backup folder
  5. submit the list of bouncing subscribers to the web application

Command line options

For a list of all command line options, run the utility with the -h flag, like:

# bin/bounce_srv -h

The easiest would be to create a script that has the following content (this is EEA specific and needs to be tweaked with the proper parameters):

bin/bounce_srv --plone_username=specialploneusername
--plone_password=specialplonepass --login_url="http://localhost:8080/site/login_form" --callback_url="http://localhost:8080/site/newsletter_theme/add_bounced_subscribers" --config_url="http://localhost:8080/site/newsletter_theme/get_service_parameters" --imap_username="zopeapps" --imap_password="imappass" --imap_server="" --imap_folder="INBOX" --imap_backup_folder="FoundBounces" --use_ssl=on

This script should be called from cron, at 6-12 hours interval.

VERP support

The best bouncing detection is provided by using the VERP concepts, which involve specifying a special email address as the value for the Return-Path header, inside the sent emails. This command line utility then tries to parse those headers and extract the newsletter id and the subscriber's email from that header.

An example of a VERP email address is:

You can notice the following information:

  1. <newsletter-id> - this will be used to identify the specific newsletter for which the subscriber bounced
  2. "no-reply" - in this case, the "no-reply" string serves two functions: separate the newsletter id from the email address, and it should also be used to allow SMTP server to properly identify that they should receive those emails. Configuring the SMTP server to receive those messages is extremely important!
  3. <DESTINATION_MAILBOX> is the 'username' part of the subscriber's email
  4. <DESTINATION_DOMAIN> is the hostname part of the subscriber's email
  5. - this is our domain, where we receive these bounced emails. Again notice that the first part of this VERP address is variable and the SMTP server should be configured to receive messages for these addresses.

Custom bouncing filters

The command line utility will read custom filters from the web application. They will be checked against the "delivery status report" subpart from an email message. In theory, all these filters shouldn't be needed.

A good start for a set of filters is this: (taken from: )

# user unknown # unknown local part # user is unknown # MAILBOX NOT FOUND # by AOL But, your recipient never logged onto their free AIM Mail account. # yahoo 554 delivery error: dd.*cannot be delivered.*disabled or discontinued.*yahoo 554 delivery error: dd This user doesn't have a.*yahoo # hotmail Requested action not taken: mailbox unavailable # 550 unrouteable address # sorry, that mailbox isn't in my list of allowed mailboxes # 551 not our customer # Addressee unknown # user not found # invalid mailbox # No such user. # DOESN'T EXIST # qmail no such mailbox # text No Such User # text No Such mailbox # easynet, text Unknown user # text Unknown mailbox # text Invalid recipient # text Recipient unknown # text, No such email # text No such mail # text unknown recipient # No such person at this address # text #5.1.0 Address rejected

System Message: ERROR/3 (<string>, line 132)

Unexpected indentation.
re.compile("55d sorry, no mailbox", re.I), # text, qmail

System Message: WARNING/2 (<string>, line 133)

Block quote ends without a blank line; unexpected unindent.

# text invalid address # text User account is unavailable # text Recipient not found # text User account is unavailable # text does not exist # text No account by that name here # text Mailbox is inactive # text Nonexistent user # text no mailbox here by that name # text mail not found # text Mailbox disabled # text No such recipient # text - 5.1.1


0.3 - (2011-11-18)

  • Rerelease broken egg

0.2 - (2011-11-18)

  • Change: cleaned up package of pylint violations [ichimdav #4140]

0.1 - (15-02-2010)

  • First release, it can connect to IMAP server, detect bounces, make a call into Plone, move processed messages into backup folder