Bounce Manager v2.1

Part of CloudWizard Email Suite

Bounce Manager connects to your bounce mailbox via IMAP, reads delivery failure notifications, classifies them as hard bounces, soft bounces, IP blocks, or spam rejects, and automatically suppresses hard-bounced addresses from future campaigns.

Requirements

Verify the IMAP extension before proceeding:

php -r "echo extension_loaded('imap') ? 'IMAP OK' : 'IMAP missing';"

If it reports missing, install it first — the module will not function without it.

Step 1 — Install the Controller

Bounce Manager is a module that runs inside the CloudWizard Controller. The controller handles authentication, shared database config, and module detection. Install it first.

public_html/CW/
  bootstrap.php
  index.php
  admin/
    setup.php
    login.php
    style.css
    ...

Step 2 — Install Bounce Manager

public_html/CW/BounceManager/
  bouncemanager.php
  bm_config.php
  module.php
  admin/
    index.php

Step 3 — Activate your license

Step 4 — Add a bounce mailbox

Bounce Manager supports unlimited IMAP accounts — one per sending domain or a single shared address.

IMAP settings by provider

Running a scan

Select the mailboxes to scan using the checkboxes, then click Run bounce scan →. A progress bar tracks the scan in real time. The page reloads automatically when finished and shows updated bounce counts. Full history is available via ↗ Scan history.

What happens during a scan

• Connects to each selected IMAP account
• Fetches up to 500 messages per account per chunk
• Applies pattern matching to classify each bounce
• Records classified bounces in cw_bounces
• Deletes matched bounce messages from the IMAP server
• Non-bounce messages are never touched

What gets deleted vs. what stays

Bounce types

How addresses are detected

Bounce Manager uses pattern matching on the email subject line and body text to identify and classify bounce messages. See the Patterns section for details on how to view and customise the matching rules.

Suppression list

Hard-bounced addresses are written to cw_mail_suppression — a shared table that Mail Engine checks before every send. Suppressed addresses are skipped automatically across all campaigns and lists.

You can also import external suppression lists (legacy unsubscribes, complaint lists) using the import_suppression.php utility included with the Email Suite.

Patterns

Bounce classification is driven by pattern rules stored in the database. The Patterns tab shows all rules in three categories:

Match types

Result types for subject rules

Adding a custom pattern

If you encounter bounce messages that are not being classified, go to Bounce Manager → Patterns, click Add Pattern, and enter the matching text from the unrecognised bounce subject or body. Set the category and result type, then save. The new rule applies on the next scan.

Exporting bounces

Export buttons at the bottom of the bounce list produce a CSV with columns: email, bounce_type, soft_count, reason, source_account, bounce_date.

Using the exclude list in PHP

// Load hard+soft bounces from exported CSV into an array
$exclude = [];
if (($fh = fopen('bounces_exclude_2026-07-01.csv', 'r')) !== false) {
    fgetcsv($fh); // skip header
    while (($row = fgetcsv($fh)) !== false) {
        $exclude[] = strtolower(trim($row[0]));
    }
    fclose($fh);
}

// Filter your list before sending
$toSend = array_filter($myList, fn($email) => !in_array(strtolower($email), $exclude));

Using the exclude list with SQL

-- Mark bounced addresses in your subscribers table
UPDATE subscribers s
JOIN cw_bounces b ON LOWER(s.email) = LOWER(b.email)
   AND b.bounce_type IN ('hard', 'soft')
SET s.emails_ok = 'N', s.bounce = 1;

Audit log

The Audit Log tab in Bounce Manager shows two tables:

Scan history

Every scan run is recorded with: date and time, account scanned, emails scanned, bounces found, IP/spam blocks, failures, messages deleted from IMAP, and duration in seconds.

Processing failures

Messages that matched a bounce subject rule but could not be fully parsed are logged here with the subject line, a body snippet, and the failure reason. Review these occasionally — they often indicate a bounce format from a new provider that needs a custom pattern added.

Cron automation

To scan automatically without manual intervention, add a cron job in Virtualmin → Scheduled Cron Jobs:

0 * * * * curl -s "https://yourdomain.com/CW/BounceManager/bouncemanager.php?action=cron_scan&key=YOURCRONKEY" > /dev/null 2>&1

Use your controller's cron_secret value as the key. The example runs every hour — adjust to match your sending volume. Once or twice daily is sufficient for low-volume senders.

PHP IMAP extension

Ubuntu / Debian with PHP-FPM

apt install php8.3-imap
systemctl restart php8.3-fpm

Virtualmin

Go to System Settings → PHP Configuration, enable the imap extension for your PHP version, restart PHP-FPM.

cPanel

Go to WHM → PHP Extensions and Applications and enable imap.

Verify

php -m | grep imap

Security

• Always use HTTPS. Bounce Manager handles IMAP passwords — never run it over plain HTTP.
• The controller admin is protected by your admin password. Use a strong password (the setup wizard enforces minimum 8 characters).
• Use a dedicated bounce mailbox where possible — not your main inbox. The scan deletes matched messages permanently.
• Restrict admin access by IP if possible. In Nginx, inside the location block for your CW directory:
  

  allow 1.2.3.4;
  deny all;

• Rotate your IMAP password periodically and update it in Bounce Manager → Mailbox settings.

Troubleshooting

CloudWizard Email Suite — Bounce Manager v2.1
cloudwizard.eu — support@cloudwizard.eu