Bounce Manager v2.1

Part of CloudWizard Email Suite

Bounce Manager connects to a bounce-handling mailbox over IMAP, classifies delivery failures as hard, soft, IP-block, or spam-reject, and automatically suppresses addresses that cross a configurable threshold — keeping your suppression list current without manual work.

Requirements

Step 1 — Install the Controller

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

public_html/CW/
  bootstrap.php
  config_path.php
  vendor/            ← bundled PHPMailer, shared across every module
  admin/
    index.php
    login.php
    logout.php
    settings.php
    setup.php
    style.css
    ...

Step 2 — Install Bounce Manager

public_html/CW/BounceManager/
  module.php
  bootstrap.php
  cron.php
  dmarc_import.php   ← one-off import of old DMARC report mails
  admin/
    _bootstrap.php
    index.php      ← Overview / Bounces / scan panel
    patterns.php
    settings.php
    _dmarc_mailboxes.php   ← DMARC mailbox form (shown on Settings)
    dmarc.php      ← DMARC reports tab
    audit.php
  lib/
    scan.php       ← IMAP scanning engine
    dmarc.php      ← DMARC report reader

Step 3 — Activate your license

Whether you purchase through cloudwizard.eu or via Gumroad, enter your license key under the controller's Settings → License key. See the Audience Manager guide for the full walkthrough if needed.

Step 4 — Add an IMAP account

Go to Bounce Manager → Settings and fill in the Add Account form:

Click Test next to the saved account to confirm the connection before relying on it — it reports the message count in the mailbox or the exact IMAP error if it fails. The Status column shows the real state: Not tested, Connected, Can't connect or Off, plus when the last check ran.

Step 5 — Set up the cron job

Nothing scans automatically without this. Bounce Manager → Settings shows the exact cron key and URL for your install:

Add it under Virtualmin → Scheduled Cron Jobs, running every 5-15 minutes. A single cron run fully drains each account's backlog (not just one batch), looping until nothing remains — so even after a large bounce spike, one run catches everything up rather than trickling in over several cycles.

Overview

The Bounces tab (Bounce Manager's landing page) shows five stat cards — Total, Hard bounces, Soft bounces, IP blocks, Spam rejects — plus the scan panel and your five most recent scans.

Bounces & scanning

Run Scan (left panel) lets you pick which active accounts to scan, then click 🔍 Scan now. The cron job does the same thing automatically (it also fetches new DMARC reports); the button is for when you want the result right away. Scanning runs in chunks over AJAX with a live progress bar — safe for very large mailboxes, since each chunk is a separate short request rather than one long one that could time out.

The Bounce List (right panel) shows every classified bounce, filterable by type, source account, and email search. Select rows with the checkboxes and click 🗑 Delete to remove entries, or use the Export row to download a CSV — Exclude list (hard+soft combined), Hard only, Soft only, or All.

Patterns

Classification runs against a pattern library you can fully edit under Patterns, seeded with sensible defaults on first install:

Each pattern has a match type (Starts with, Contains, or Regex), a result type, a sort order (lower runs first), and an Active toggle — turn a pattern off without deleting it if it's causing false positives.

Settings

IMAP accounts are also managed on this page — see Step 4.

DMARC reports

Big providers (Google, Microsoft, Mail.ru, Yahoo and others) send a daily summary of all mail they received in your domain's name: which server sent it, and whether it passed the DKIM and SPF checks. Bounce Manager → DMARC reads these reports and shows totals per domain and provider, your sending servers and how many messages passed, and a day-by-day list with each provider's decision. Mail that fails here is the usual reason for spam-folder delivery, and unknown server addresses can reveal someone forging your domain.

Reports are stored in compact form (zip, gzip and plain XML are understood), duplicates are ignored, and entries older than 400 days are removed automatically.

Audit Log

Three panels: an Account Summary (lifetime totals per source account, with scan count and last-scan time), a Scan History of the last 50 runs, and a Processing Failures log — messages that matched a bounce pattern but where no recipient email could be extracted from the body. Both the Scan History and Failures logs have a Clear button to wipe them if they grow large; this only clears the log, never the classified bounces themselves.

How classification works

For each message: the subject is checked against Subject Rules first. If a rule resolves straight to a type, that's used; if a rule says check, the body is scanned next — for known SMTP status codes (5xx → hard, 4xx → soft), quota/mailbox-full phrases (→ soft), and known hard-failure phrasing (user unknown, account disabled, etc.). Every message is also independently checked against the IP Block and Spam Reject body patterns regardless of what the subject rule decided, so those two categories are never missed even if a message also happens to match a generic hard-bounce subject.

The recipient's email address is extracted from the bounce body using a cascade of methods, from most to least reliable: RFC 3464 Final-Recipient/Original-Recipient headers, VERP-style Return-Path addresses, Postfix-style inline addresses, keyword-based patterns ("failed recipient:", "delivered to:"), the X-Failed-Recipients header, the original message's To: header, and finally the first plausible non-system email address found anywhere in the body. If none of these succeed, the message is logged to Processing Failures rather than silently dropped.

Security

• Always use HTTPS. IMAP credentials and bounce data should never travel over plain HTTP.
• The cron URL contains a secret key — don't share it publicly. Running the script directly on the server requires no key, since shell access is already a higher trust level.
• IMAP passwords are stored in the database — restrict database access appropriately, same as any other credential the suite stores.
• Restrict admin access by IP if possible, in Nginx:
  

  allow 1.2.3.4;
  deny all;

Troubleshooting

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