CloudWizard IMAP Bounce Manager

This guide covers installation, configuration, and daily use of the CloudWizard IMAP Bounce Manager. The tool scans your email inboxes for bounce messages, classifies them, and builds a clean exclude list for your mailing campaigns.

Requirements

Installing the PHP IMAP extension

Ubuntu / Debian (Nginx + PHP-FPM)

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

cPanel shared hosting

Go to cPanel → Select PHP Version → Extensions and enable imap. Save and apply.

Plesk

Go to Tools & Settings → PHP Settings, select your PHP version, and enable the imap extension.

Verify the extension is loaded

php -m | grep imap

Should output: imap

Database Setup

Create a dedicated database and user for the bounce manager. Log into MySQL/MariaDB as root:

mysql -u root -p

CREATE DATABASE bounce_handler CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
CREATE USER 'bounce_user'@'localhost' IDENTIFIED BY 'YourStrongPassword';
GRANT ALL PRIVILEGES ON bounce_handler.* TO 'bounce_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Upload & Configure

define('DB_HOST', 'localhost');
define('DB_NAME', 'bounce_handler');
define('DB_USER', 'bounce_user');
define('DB_PASS', 'YourStrongPassword');

Nginx Configuration

Add a location block with HTTP basic authentication. Create a password file first:

apt install apache2-utils   # provides htpasswd
htpasswd -c /etc/nginx/.htpasswd admin

Then add to your Nginx server block:

location /tools/ {
    auth_basic           "CloudWizard";
    auth_basic_user_file /etc/nginx/.htpasswd;

    # Increase upload limit for the DB updater CSV
    client_max_body_size 20M;
}

nginx -t && systemctl reload nginx

Apache Configuration

Create a .htaccess file in the same directory as imapbm.php:

Options -Indexes
AuthType Basic
AuthName "CloudWizard"
AuthUserFile /path/to/.htpasswd
Require valid-user

# Increase upload limit for the CSV updater
php_value upload_max_filesize 20M
php_value post_max_size 20M

Create the password file:

htpasswd -c /path/to/.htpasswd admin

Make sure AllowOverride AuthConfig is set in your Apache virtual host, or AllowOverride All. On cPanel hosts this is typically already enabled.

PHP upload limits on shared hosting

If you cannot use .htaccess to set PHP limits, look for a php.ini or user.ini file in your home directory:

upload_max_filesize = 20M
post_max_size = 20M

First Run

Open the tool in your browser. On first load it will:

• Create the imap_accounts, bounces, bounce_patterns, bounce_failures, and audit_log tables
• Seed 20+ default bounce patterns (subject rules, IP block keywords, spam reject keywords)

You should see the Bounces tab with empty stats and a prompt to add your first account in Settings.

Overview

The IMAP Bounce Manager has four tabs:

Adding IMAP Accounts

Go to Settings and fill in the form:

Click Test after saving to verify the connection. A successful test shows the message count in the mailbox.

Common IMAP settings

Scanning

On the Bounces tab:

1. Check the accounts you want to scan in the left panel
2. Click Scan & Process
3. The tool fetches up to 500 messages per account, classifies bounce emails, logs them to the database, and deletes matched messages from the IMAP server
4. A summary appears below the button showing counts and a per-message log

What gets deleted vs. what stays

Bounce Types

How addresses are detected

The tool uses a priority chain to extract the bounced email address from each message:

1. RFC 3464 Final-Recipient header — the most reliable method, used by all standard DSN-compliant mail servers
2. Original-Recipient header — fallback DSN header
3. VERP pattern — decodes bounce+user=domain.com@sender.com Return-Path addresses
4. Postfix body pattern — matches <email>: in the Postfix NDR body
5. X-Failed-Recipients header
6. To: header of the original message
7. First non-system email address in the body — last resort

If no address can be extracted, the message is logged to the Failure Log and deleted from IMAP.

Patterns

The Patterns tab shows all rules used to detect and classify bounce messages. There are three categories:

Match types

Result types for subject rules

Adding a custom pattern

Click Add Pattern, choose category and match type, enter your pattern text, and set the result type. Use Sort Order to control which rules are checked first — lower numbers run first.

Exporting the Bounce List

The export buttons at the bottom of the Bounces tab produce a CSV file with these columns:

email, bounce_type, soft_count, reason, source_account, bounce_date

Using the exclude list in PHP

// Load the exclude list from CSV into an array
$exclude = [];
if (($fh = fopen('bounces_exclude_2026-06-15.csv', 'r')) !== false) {
    fgetcsv($fh); // skip header
    while (($row = fgetcsv($fh)) !== false) {
        $exclude[] = strtolower(trim($row[0]));
    }
    fclose($fh);
}

// Filter your subscriber list before sending
$to_send = array_filter($subscribers, function($sub) use ($exclude) {
    return !in_array(strtolower($sub['email']), $exclude);
});

Using the exclude list with a SQL JOIN

If you imported the CSV into a bounces table on the same server, you can exclude at query time:

SELECT s.* FROM signups s
WHERE s.hard_bounce = 0
  AND s.email NOT IN (
    SELECT email FROM bounce_handler.bounces
    WHERE bounce_type IN ('hard', 'soft')
  );

Database Updater Tool

The included update_hard_bounces.php is a standalone web tool that reads an exported hard bounce CSV and sets hard_bounce = 1 in your subscriber table.

define('DB_HOST', 'localhost');
define('DB_NAME', 'your_database');
define('DB_USER', 'your_user');
define('DB_PASS', 'your_password');
define('SIGNUPS_TABLE', 'signups');

Customising for your schema

If your subscriber table uses different column names, edit these two lines in the script:

// Change 'email' to match your email column name
$email_col = array_search('email', array_map('strtolower', $header));

// Change 'hard_bounce = 1' to match your flag column
$stmt = $pdo->prepare("UPDATE " . SIGNUPS_TABLE . " SET hard_bounce = 1 WHERE email = ?");

Audit Log

The Audit Log tab 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
• 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 to check if you need to add a new pattern for an unusual bounce format.

Troubleshooting

Security Recommendations

• Always use HTTPS. The tool handles IMAP passwords — never run it over plain HTTP.
• Always use HTTP basic auth or equivalent access control. The tool has no built-in login system.
• Restrict by IP if possible — in Nginx: allow 1.2.3.4; deny all; inside the location block.
• Do not put it in a public directory without access control. The scan action deletes emails from your server.
• Use a dedicated IMAP account for bounces where possible — not your main inbox.
• Rotate the database password periodically and update the constant in imapbm.php.

Changelog

v2.0

• Patterns moved to database — fully editable in UI without touching code
• VERP bounce address detection added
• Audit log with per-scan statistics and duration
• Failure log for unparseable messages
• Spam Reject bounce type added (separate from IP Block)
• Body extraction improved — walks full MIME tree including delivery-status parts
• set_time_limit(0) prevents timeouts on large inboxes
• Fixed: ssl reserved word in MariaDB (renamed to use_ssl)
• Fixed: non-UTF8 characters in bounce reason causing MariaDB errors
• Fixed: PHP 8.1+ IMAP\Connection type hint

v1.x

• Initial release with hard/soft/ip_block classification
• Multi-account IMAP scanning
• CSV export and DB updater tool
• Account management UI in Settings tab