Bounce is a full-featured Drupal 7 module for managing non-delivery reports generated by outgoing mail: it retrieves the reports and uses them to decide when to block mail to specific addresses. This helps prevent poor deliverability, blacklisting, and all of the other undesirable things that can happen when your site behaves more like a spam source than a responsible internet citizen. Bounce also provides an administrative interface that shows current status, blocked addresses, non-delivery reports, and so forth.

The 7.x-1.0 release of Bounce assumes that all outgoing mail is sent using drupal_mail() - i.e. that the underlying mail module implements MailSystemInterface as the basis for its functionality. The reason for this is that Bounce's hook_mail_alter() implementation is where some of the magic happens: adding headers, keeping track of what's been sent, and blocking mails that shouldn't go out. If you want hook_mail_alter() to be invoked, then mail must pass through drupal_mail().

Unfortunately mail modules in Drupal tend to be hit and miss on that count. For every module like PHPMailer or Swift Mailer that does in fact provide a MailSystemInterface - i.e. does things properly - there is another that departs from the beaten path to send mail its own way. It is particularly common for bulk mail implementations to sidestep the use of drupal_mail() and not implement MailSystemInterface. See ManyMail, for example.

Far be it from me to judge, however. Some of the obvious optimizations for bulk sending are harder to accomplish when running through drupal_mail(), which adds overhead and integration with other hook-implementing modules that may or may not be desired. So as of version 7.x-1.1, I've made it easier to use Bounce when your mail module of choice runs independently of Drupal's core mail APIs. This will still require a little integration code, but the situation is a great improvement over 7.x-1.0:

1) Install and configure bounce as usual

Your outgoing mails should include a Return-Path header that points to a mail account you control, distinct from any From or other origination header. This account is where non-delivery reports end up. Configure Bounce to access this Return-Path account and read its mail.

2) Add a unique identifier header to each outgoing mail

How this is done is up to you, and is no doubt very dependent on your mail-sending code. You can use any header key, and any form of unique ID provided it is no longer than 255 characters (i.e. it will fit into Bounce's schema).

3) Let Bounce know about the unique identifier header key

If you are setting the header "x-my-unique-mail-id" in your outgoing mails then you will have to set the "bounce_mail_header_name" variable, either in code or configured via the general settings administration form.

variable_set('bounce_mail_header_name', 'x-my-unique-mail-id');

Bounce will then search for that header when processing non-delivery reports, using it as the preferred way to link reports to earlier outgoing emails.

4) Tell Bounce about outgoing mail as it is sent

Every time you send mail, you must call bounce_record_sent_mails() in order to pass to Bounce the recipient email addresses and unique header IDs for each piece of outgoing mail. For example:

$mail_data = array();
$mail_data[] = array(
  'mail' => 'recipient_1@example.com',
  'header_id' => 'some form of UUID #1',
);
$mail_data[] = array(
  'mail' => 'recipient_2@example.com',
  'header_id' => 'some form of UUID #2',
);

// ... etc ...

bounce_record_sent_mails($mail_data);

The function is more efficient if you pass in data on many mails at once, so if you send in batches then call it less frequently and with larger sets of data.

5) Ask Bounce which email addresses are blocked

Before sending mail, ask Bounce which email addresses are blocked and should not be sent further mail by using the bounce_determine_blocked_addresses() function. Given an array of addresses, it will return those that are blocked. For example:

$addresses = array(
  'is_this_blocked_1@example.com',
  'is_this_blocked_2@example.com',
  // ... etc ...
);
$blocked_addresses = bounce_determine_blocked_addresses($addresses);

It is up to you to then remove these addresses and refrain from sending mail to them. Like bounce_record_sent_mails(), this function is more efficient if you pass in many addresses at once rather than one at a time.