Guides & TutorialsTroubleshooting Email TroubleshootingTroubleshooting Email Sending Problems

Troubleshooting Email Sending Problems

This article describes troubleshooting for WHMCS 8+. For help with WHMCS 7.x, see Troubleshooting Email Sending Problems.

If your WHMCS installation isn't sending emails or they aren't formatted as expected, follow these troubleshooting steps.

First, navigate to Configuration > System Logs.

Then, review the logs for any error messages at the time of email sending.

Could not instantiate mail function

This error occurs when you have selected PHP Mail as your mail type for the Mail Provider setting. It means that, when attempting to send the email, the mailserver rejected it.

The PHP Mail function uses the server's mail()  function, which is not always reliable. It also doesn't generate a friendly error.

Switching to another Mail Provider under Configuration > System Settings > General Settings > Mail is faster, safer and would allow you to have more descriptive errors when an issue does occur. These other methods are also usually more reliable when sending emails.

Alternative server-side configuration changes which might resolve PHP mail() issues:

  • Install a local mail server (e.g. postfix).
  • Ensure that your sendmail_path points at the sendmail binary (usually /usr/sbin/sendmail) in your php.ini. Note that on Ubuntu/Debian you may have multiple .ini files in /etc/php5/mods-available and possibly other locations.
Could not connect to SMTP host

There are several possible reasons for this error:

  • The SMTP settings that you entered under Configuration > System Settings > General Settings > Mail > Mail Provider are incorrect. Check with your system administrator to ensure that you entered the correct SMTP Port, SMTP Host, SMTP Username, SMTP Password, and SMTP SSL Type for use with your mail server.
  • You're using an inappropriate SMTP Port with the SMTP SSL Type option selected. For example, selecting SSL and the port number 25 would cause this error. The most common port assignments by SSL type are: 
SSL Type Post Number
25 or 26
SSL 465 or 587
TLS 587
  • The mail server is blocking connections from the server that hosts your WHMCS installation.
  • The server that hosts your WHMCS installation is blocking outgoing connections to the mail server.

Work with your server administrator or hosting provider to resolve these issues.

Could Not Authenticate

This indicates that the mail server is rejecting the SMTP details in Configuration > System Settings > General Settings > Mail > Mail Provider. Make sure that they are correct.

Be aware of SMTP restrictions on cPanel & WHM servers. SMTP restrictions will automatically reroute any SMTP traffic leaving the server back to localhost (the server WHMCS is on). To prevent this problem, in WHM, navigate to Home >> Security Center >> SMTP Restrictions to be sure the option is disabled.

If you are using Google Mail, this could also be due to the security settings in your email account. Refer to these Google Mail troubleshooting resources:

Sender Verify Failed

A Sender Verify Failed error indicates that the sending email address does not exist on the SMTP server.

To confirm this, log in to cPanel and navigate to Home >> Email >> Email Accounts.

Note the email accounts on this page:

In WHMCS, navigate to Setup > General Settings.

Verify that the Email Address value here matches one of the email addresses you saw in cPanel.

Syntax Error

Syntax errors are usually due to invalid code in the email template.

The error in Configuration > System Logs provides the following debugging information:

  1. The error.
  2. The line number of the invalid syntax within the email template.
  3. The code surrounding the error.

To resolve the error, navigate to Configuration > System Settings > Email Templates and click on the email template. In this example it's the Client Signup Email template.

Review the code of the email template and correct any errors.

In this example, an erroneous {if} is in the email template. Removing it will correct the syntax.

Click Save Changes.

Smarty Error: Not allowed by security policy

A Smarty Security Policy Error means that the email template contains advanced code that the default email security policy blocks.

First, review the code in the email to confirm what it's trying to send. This is done in Configuration > System Settings > Email Templates.

You can then add an exception to the email security policy to allow the particular piece of code in use.

For a more detailed explanation of the security policy and instructions for adding an exception, see our Smarty Security Policy documentation.

Data Not Accepted

A Data Not Accepted error occurs when the email is rejected by your mail server. There could be many reasons for this, so consulting with your mail server administrator is the best option.

Follow these steps to obtain more verbose output from your mail server, which should provide more insight into the precise cause:

Some of the common causes are also itemised below:

Mail server does not allow different sender addresses and usernames

Some servers require that the From email address is the same as the User used to authenticate. To assess this:

  1. Navigate to Configuration > System Settings > General Settings > Mail tab
  2. Click Configure Mail Provider
  3. Observe the SMTP Username value
  4. Close the modal and scroll down
  5. Observe the System Emails From Email setting
  6. Navigate to the General tab
  7. Observe the Email Address setting
SMTP Username
System Emails From Email
Email Address

If the values are different, check with your email provider that the SMTP User is authorized to send emails with the System Emails From Email address as the sender.

If this is not permitted, adjust the System Emails From Email setting to match the SMTP Username value.

The file size of your message is too large

If sending of emails with attachments fail, try removing the attachment from the email template via Configuration > System Settings > Email Templates > Edit

The receiver might be blacklisted or blocked by the SMTP server

Check your server's spam filtering settings

Email sending rate-limiting has been triggered on the SMTP server

This is the most likely cause if the Data Not Accepted error occurs intermittently with a range of different email messages.

Wait a few hours before sending further emails.

If the email then sending succeeds without any other changes to the WHMCS settings and mail server configuration,  contact your mail server administrator to increase the email sending limits on the SMTP User.

Email sending aborted by configuration

In WHMCS 8.1, this error indicates that you have set Disable Email Sending to ON at Configuration > System Settings > General Settings in the Mail tab. The system will log this error every time that you enable or disable this setting.

We recommend that you only enable this setting when you are testing updates or customizations on a development installation or while troubleshooting. For more information, see Disabling Outgoing Mail.

SMTP connect () failed

The full error is typically displayed with a troubleshooting URL:

SMTP connect() failed.

This error is typically caused by one of the following:

  1. DNS failure - the server cannot resolve the supplied SMTP Host
  2. Firewall block - A firewall rule is preventing the server connecting to the supplied SMTP Host
  3. Remote SMTP Disabled - The server configuration may prevent the use of external SMTP servers
  4. SSL Certificate Miss-configuration - A certificate on the hostname certificate on the SMTP server may be expired 

To identify the specific cause, follow the advanced troubleshooting steps to enable verbose output of the SMTP connection.

No recipients provided for message

The Client Account has opted out of receiving this type of email via their Email Notification preferences.

To receive this email, the corresponding Email Notification preference must be checked for the Client Account or one of the Contacts:

  • The Client Account Email Notification preferences are managed via the Profile tab.
  • The Contact Email Notification preferences are managed via the Contacts tab.


In this example, attempting to send a Product Welcome Email would result in a No recipients provided for message error, as the Product Emails checkbox is unchecked on both the Profile and Contacts tab.

Client Profile Tab
Client Contacts tab

To resolve the error, check the Product Emails checkbox for in at-least one location.