Troubleshooting System Email
If you encounter errors or issues while sending email to your clients or configuring your mail provider, see the sections below to start troubleshooting and resolve the issue.
Troubleshooting for SMTP
You can begin the troubleshooting process for many SMTP-related issues by enabling Debugging for your mail provider in the Mail tab at Configuration () > System Settings > General Settings (or, in WHMCS 8.5 and earlier, SMTP Debug).
You can also enable SMTP debugging by adding
$smtp_debug = true to your configuration.php file.- For more information about email features in WHMCS, see Email and Mail Providers.
- For general steps to troubleshoot problems in WHMCS, see Start Troubleshooting.
General Email Issues
You may encounter the following common issues:
| Error or Issue | Explanation | Next Steps |
|---|---|---|
| External systems are flagging your WHMCS installation’s emails as spam or rejecting them. | This is usually due to the server configuration. | Email Flagged as Spam |
| You see a syntax error when troubleshooting email-related issues. | Syntax errors are usually due to invalid code in the email template. | Email Template Syntax Errors |
Data Not Accepted | The mail server rejected email. This can occur for many reasons. | Data Not Accepted Errors |
Error: the single id was not found in response | When WHMCS attempted to import the message, it did not exist in the mailbox. | Single ID Errors |
TypeError: array_search(): Argument #2 ($haystack) must be of type array | An invalid value in the Email Marketer rule (a missing billing cycle) causes an error in PHP 8.1 environments only. | Could Not Instantiate Errors |
Sending Failures
You may encounter the following common issues that prevent mail from sending:
| Error or Issue | Explanation | Next Steps |
|---|---|---|
| The system isn’t sending support ticket notification emails. | This issue is usually due to a misconfiguration. | Unsent Ticket Notifications |
| The system is not sending product welcome emails. | This is usually due to a problem with account creation, or you may not have configured a welcome email. | Unsent Welcome Emails |
| The system is not successfully sending general emails, like client sign-up or order confirmations. | This issue is usually due to a misconfiguration. | Unsent General Emails |
Email sending aborted. | This error indicates that an unknown issue has prevented the email from sending. This commonly occurs when there is a configuration issue with the file paths at Configuration () > System Settings > Storage Settings. | Sending Aborted Errors |
Email Send Aborted By Hook | This error indicates that a custom hook has prevented the email from sending. | Sending Aborted By Hook |
Email sending aborted by configuration | This error indicates that you have set Disable Email Sending to ON. | Sending Aborted Configuration |
Message Body Empty | A syntax error occurred, preventing the email from sending. | Message Body Empty Errors |
Sending Failed. Please see documentation. | The API command cannot send the specified email template type for the messagename parameter. | SendEmail Sending Failure |
Smarty Error: Not allowed by security policy | The email template contains advanced code that the default email security policy blocks. | Smarty Policy Errors |
Recipient-Related Issues
You may encounter the following common issues with email recipients:
| Error or Issue | Explanation | Next Steps |
|---|---|---|
Administrators receive an email with two To email headers, one of which is to undisclosed-recipients. | The email is addressed to the same admin email address in both the To and BCC fields. | Undisclosed Recipients |
No recipients provided for message | The client has opted out of receiving this type of email in their Email Notification preferences. | No Recipients Errors |
The following recipients failed | This error is often due to a misaddressed email. | Failed Recipients |
Mail Provider-Related Issues
You may see certain common issues related to your system mail provider:
Microsoft®
You may encounter the following common issues with Microsoft:
| Error or Issue | Explanation | Next Steps |
|---|---|---|
Connection unsuccessful. Please close this window and try again. | The Application (client) ID and Client Secret combination for your Microsoft Entra® ID (formerly Microsoft Azure®) app are invalid. | Microsoft Connection Unsuccessful |
Failed to Create $app_name application. Error detail URL may not contain a query string. | Microsoft Entra apps do not support the redirect URI format in WHMCS. | Microsoft Mail Query Errors |
PHP Mail
You may encounter the following common issues with PHP mail:
| Error or Issue | Explanation | Next Steps |
|---|---|---|
Call to undefined function PHPMailer\PHPMailer\escapeshellarg() | Your system is missing the escapeshellarg PHP extension. | Undefined PHPMailer Function Errors |
Could not instantiate mail function | You have selected PHP Mail as your Mail Provider setting. | Could Not Instantiate Errors |
SMTP
You may encounter the following common issues with SMTP:
| Error or Issue | Explanation | Next Steps |
|---|---|---|
Could Not Authenticate | The mail server is rejecting the SMTP details that you entered for your mail provider. | SMTP Authentication Errors |
Could not connect to SMTP hostor SMTP connect() failed. | This error could indicate incorrect mail provider settings, a problem with the external mail server, or one of several other issues. | SMTP Connection Errors |
Sender Verify Failed | This error indicates that the sending email address is invalid or does not exist on the SMTP server. | Sender Verify Failed Errors |
SMTP ERROR: Password command failed | This error occurs because Microsoft no longer supports basic SMTP authentication. | SMTP Password Command Failed Errors |
Email Marketer
You may encounter the following common issues while using the email marketing system at Utilities > Email Marketer:
| Error or Issue | Explanation | Next Steps |
|---|---|---|
TypeError: array_search(): Argument #2 ($haystack) must be of type array, null given in /path/to/whmcs/vendor/whmcs/whmcs-foundation/lib/Cron/Task/EmailMarketer.php:0 | An invalid value in the Email Marketer rule (a missing billing cycle) causes an error in PHP 8.1 environments only. | Email Marketer TypeErrors |
Support Tickets
For issues with email piping, email importing, or other support ticket-related email, see Troubleshooting the Support System.
Renewal Notices and Payment Reminders
You may encounter the following common issues:
| Error or Issue | Explanation | Next Steps |
|---|---|---|
| The domain renewal link in domain renewal reminder emails is broken. | In some PHP server configurations, the system generates the URL for the domain renewal link in domain renewal reminder emails incorrectly. | Broken Renewal Links in Emails |
| The system sent two copies of the same renewal notice or payment overdue reminder email. | This issue may be due to the system cron running twice at the same time. | Duplicate Invoices |
Last modified: January 17, 2025