Diagnose Mail Failures and Forwarders via Terminal

This guide explains how to use the Mail Failure / Forwarder Report on a cPanel and WHM server.

The script analyzes Exim logs, configured forwarding addresses, MailChannels rejection messages, cPanel max-defers policy blocks, deferred deliveries, original senders, and rolling failure bursts.

It is especially useful when a domain suddenly cannot send mail because external forwarding failures caused cPanel's maximum defers or failures protection to activate.

Step-by-Step Instructions

Step 1: Log in to the Server as Root

Connect to the affected cPanel server using SSH and log in as root.

ssh root@your-server-ip

You can also log in to WHM as root and open:

WHM → Server Configuration → Terminal

Root access is required.
The script reads system Exim logs under /var/log/exim_mainlog* and cPanel forwarding configuration files under /etc/valiases/.

Step 2: Run the Mail Failure Report

Run the following command:

curl -fsSL https://fixyourwordpress.com/mail_failure_reportV2.sh | bash

The script reads its prompts directly from /dev/tty, so it remains interactive even when downloaded and piped through curl.

Step 3: Enter the Domain Name

When prompted, enter the domain you want to investigate.

Enter the domain to investigate: example.com

Enter only the domain name. Do not include:

https://
www.
An email address
A URL path

Valid examples include:

example.com
DOMAIN.EXT
customer-domain.net

Step 4: Enter the Start Date

The script asks for the beginning of the reporting period.

Start date [2026-07-23]:

Press Enter to accept the default date, which is normally four days before the current date.

To use a different date, enter it in:

YYYY-MM-DD

Example:

2026-07-20

The report searches the currently available Exim logs. If the requested date is older than the server's retained log history, older events may no longer be available.

Step 5: Wait for the Log Analysis

The script reads the active and rotated Exim logs, then filters entries related to the selected domain.

[INFO] Reading Exim logs from 2026-07-23 onward...

Large or busy servers may contain millions of Exim log lines. The report builds a temporary workspace under /tmp and automatically removes it when complete.

Step 6: Review the Executive Summary

The first report section summarizes the overall findings.

================================================================================
EXECUTIVE SUMMARY
================================================================================
Domain-related Exim log lines:             2556
All hard-failure lines (**):               142
All deferred lines (==):                   58
Real MailChannels forwarding failures:     17
cPanel max-defers policy discards:         112
Successful MailChannels forwarded sends:   228

Likely finding:
External forwarders generated enough MailChannels rejections to contribute to
the domain reaching its cPanel max-defers/max-failures protection threshold.

The summary separates genuine remote delivery failures from the later policy blocks generated by cPanel.

Step 7: Review Configured Forwarders

The report reads:

/etc/valiases/example.com

It displays:

All active forwarding entries
External forwarding destinations
The domain catch-all configuration

================================================================================
CONFIGURED FORWARDERS
================================================================================

--- All active valiases entries ---
sales: localuser, outside@example.net
info: employee@gmail.com
*: :fail: No Such User Here

--- External forwarders only ---
sales -> outside@example.net
info -> employee@gmail.com

--- Catch-all entry ---
*: :fail: No Such User Here

External forwarders are important because forwarded messages may be rejected by the destination provider even when the original sender was not the domain owner.

Step 8: Review Real MailChannels Failures

The report identifies failures routed through:

R=send_via_mailchannels

These are genuine attempts to forward mail externally through MailChannels.

The report groups failures by:

Local forwarding address
External destination
MailChannels rejection code
Rejection reason
Clock hour

================================================================================
REAL MAILCHANNELS FORWARDING FAILURES
================================================================================

--- Failure count by local forwarder and external destination ---
     12 sales@example.com -> employee@gmail.com
      5 info@example.com -> outside@example.net

--- Failure count by local forwarder and MailChannels code ---
     10 sales@example.com rspamd-001
      7 info@example.com sndr-001

--- MailChannels rejection reasons ---
     12 550 5.7.1 Message rejected due to policy
      5 550 5.7.1 Sender rejected

--- Genuine MailChannels failures per clock hour ---
      7 2026-07-23 10:00
     10 2026-07-23 11:00

Step 9: Review Rolling 60-Minute Failure Bursts

The report looks for any moving 60-minute period containing five or more genuine MailChannels forwarding failures.

================================================================================
ROLLING 60-MINUTE FAILURE BURSTS
================================================================================

--- Rolling 60-minute windows containing 5 or more failures ---
  7 failures from 2026-07-23 10:14:03 through 2026-07-23 10:58:45
  9 failures from 2026-07-23 10:22:18 through 2026-07-23 11:15:41

This is more accurate than grouping failures only by fixed clock-hour buckets.

For example, four failures at 10:50 and four more at 11:10 occurred within 20 minutes, even though they appear in separate clock hours.

Step 10: Review cPanel Policy Discards

The report separately identifies failures generated by:

R=enforce_mail_permissions

These entries indicate that cPanel's max-defers or max-failures policy had already been triggered.

================================================================================
CPANEL MAX-DEFERS / MAX-FAILURES POLICY DISCARDS
================================================================================

--- Policy discard count by external destination ---
     84 employee@gmail.com
     28 outside@example.net

--- Policy discard count by local forwarding address ---
     84 sales@example.com
     28 info@example.com

Do not treat these policy discards as the original cause.
They are generally the result of the domain already exceeding its failure or defer threshold. The original cause is usually found earlier in the genuine MailChannels forwarding failures.

Step 11: Review All Failure and Defer Destinations

The report ranks all hard failures and temporary deferrals by destination.

================================================================================
ALL FAILURE AND DEFER DESTINATIONS
================================================================================

--- All hard failures by destination ---
    112 employee@gmail.com
     24 outside@example.net
      6 another@example.org

--- All deferrals by destination ---
     31 employee@gmail.com
     18 outside@example.net
      9 another@example.org

In Exim logs:

Marker	Meaning
`**`	Hard delivery failure
`==`	Temporary deferral
`=>`	Successful delivery
`<=`	Message received by Exim

Step 12: Identify the Original Senders

For each MailChannels forwarding failure, the script attempts to locate the original message reception line and extract its envelope sender.

================================================================================
ORIGINAL SENDERS BEHIND MAILCHANNELS FORWARDING FAILURES
================================================================================

--- Original envelope senders ranked by count ---
     14 newsletter@example-store.com
      8 alerts@example-service.net
      5 promotions@example-shop.org

--- Original sender domains ranked by count ---
     14 example-store.com
      8 example-service.net
      5 example-shop.org

This helps identify whether rejected forwarded messages came from:

Mailing lists
Newsletters
Automated notifications
Spam campaigns
Legitimate senders with poor forwarding compatibility

Step 13: Review Recent Raw Examples

The report includes recent raw Exim entries for:

Real MailChannels failures
cPanel max-defers policy discards

These examples provide the complete router, transport, destination, response code, and rejection text needed for manual verification.

Step 14: Review the Final Assessment

The final section evaluates the relationship between genuine forwarding failures and cPanel policy blocks.

================================================================================
ASSESSMENT
================================================================================
External forwarding failures were found, followed by cPanel policy discards.
This strongly indicates that rejected forwarded mail contributed to the domain
reaching its max-defers/max-failures threshold.

At least one rolling 60-minute period contained five or more genuine failures.
This is more meaningful than grouping failures into fixed clock-hour buckets.

Recommended review:
1. Review the highest-count external forwarders.
2. Review the original sender and sender-domain rankings.
3. Remove obsolete forwarders or update subscriptions to destination addresses.
4. Review the domain max-defers threshold if it is set unusually low.
5. Do not treat enforce_mail_permissions discards as the original root cause.

Step 15: Open the Saved Report

The completed report is saved under /root with the domain and timestamp in its filename.

/root/mail_failure_report_example.com_20260727_123810.txt

Open it with:

less /root/mail_failure_report_example.com_20260727_123810.txt

Search inside the report by pressing /, entering a mailbox, destination, IP, or error code, and pressing Enter.

What This Script Checks

Current and rotated /var/log/exim_mainlog* files
Domain-related Exim log entries
Hard delivery failures
Temporary delivery deferrals
Successful MailChannels forwarded deliveries
Real MailChannels forwarding rejections
cPanel max-defers and max-failures policy blocks
Configured cPanel forwarding addresses
External forwarding destinations
Domain catch-all configuration
MailChannels rejection codes and reasons
Failures by forwarding address and destination
Rolling 60-minute failure bursts
Original envelope senders
Original sender domains
Recent raw failure examples

Understanding Forwarding Failures

Email forwarding can cause delivery failures even when the original message was successfully accepted by the cPanel server.

A typical forwarding path looks like:

Original sender
      ↓
cPanel mailbox or forwarder
      ↓
MailChannels
      ↓
External destination provider

The destination provider may reject the forwarded message because of:

Sender reputation
SPF alignment
DKIM alignment
DMARC policy
Spam filtering
Mailing-list content
Destination-specific forwarding restrictions
MailChannels acceptable-use policy checks

Repeated failures can count against the cPanel account's defer and failure limits.

Real Failure vs. Policy Block

Log Router	Meaning	How to Treat It
`R=send_via_mailchannels`	MailChannels attempted delivery and the external destination or filtering service rejected the message.	Treat this as a genuine forwarding failure and investigate the sender, forwarder, destination, and rejection reason.
`R=enforce_mail_permissions`	cPanel blocked the attempt because the domain had already exceeded its permitted failure or defer threshold.	Treat this as a symptom of the threshold being reached, not the original failure.

Recommended Corrective Actions

Review the external forwarders with the highest number of genuine MailChannels failures.
Confirm that each forwarding address is still required and points to a valid destination.
Remove obsolete forwarding addresses.
Where possible, update newsletters, mailing lists, invoices, alerts, and subscriptions to send directly to the external destination instead of forwarding through the cPanel server.
Review the original sender rankings to identify recurring problem senders.
Review MailChannels rejection codes and response messages.
Confirm that the domain's SPF, DKIM, and DMARC configuration is valid.
Check whether the cPanel max-defers threshold is unusually low.
Avoid simply raising the threshold without correcting broken or obsolete forwarders.
Re-run the report after changes to confirm that genuine forwarding failures have stopped.

Important Notes

Forwarding is not the same as direct delivery.
A message that passes filtering when sent directly to Gmail, Outlook, or another provider may still be rejected when forwarded through a cPanel server.

The script must be run as root
The report only covers Exim logs still retained on the server
Older failures may have already rotated out
The report file is created with permissions set to 600
Temporary working files are removed automatically
The default start date is four days before the current date
The end date is always the current server date
The script does not modify Exim, cPanel, forwarders, or mailboxes
The script is diagnostic only
Raw log examples may contain email addresses and delivery details

Example Customer Explanation

We found that external email forwarders on the domain generated repeated MailChannels delivery rejections. Once enough failures occurred within a short period, cPanel's maximum defers and failures protection began blocking additional outgoing and forwarded messages. The later cPanel policy blocks were a result of the earlier forwarding failures, not the original cause. We recommend reviewing and removing obsolete forwarders and updating recurring senders or subscriptions to deliver directly to their final destination addresses.

Command Summary

Run the interactive report:

curl -fsSL https://fixyourwordpress.com/mail_failure_reportV2.sh | bash

View the finished report:

less /root/mail_failure_report_example.com_YYYYMMDD_HHMMSS.txt

Search the report for MailChannels:

grep -i "mailchannels" /root/mail_failure_report_example.com_*.txt

Search the report for cPanel policy blocks:

grep -i "enforce_mail_permissions" /root/mail_failure_report_example.com_*.txt