Skip to content
Management

WHMCS Email Not Sending? Fixes in Order of Likelihood (2026)

WHMCS email usually fails because PHP Mail is rejected, the SMTP port and SSL type don't match, or SPF, DKIM and DMARC are missing. Check System Logs first, then fix in order.

WHMCSPilot Team Published Updated 11 min read
WHMCS Email Not Sending? Fixes in Order of Likelihood (2026)

WHMCS emails usually stop sending for one of three reasons: the receiving server rejects PHP Mail, the SMTP port and encryption type don't match, or Gmail and Yahoo refuse mail from a domain without SPF, DKIM and DMARC. This guide is for admins of self-hosted WHMCS 8.13 and 9.x, and it works through the fixes in order of likelihood, starting with the two logs that tell you which problem you have.

Key takeaways

  • Check Configuration > System Logs first. A message in the Email Message Log with no error in the Activity Log left WHMCS, so the problem is delivery, not sending.
  • Switch the mail provider from PHP Mail to SMTP or a built-in provider on the Mail tab, and match the port to the SSL type: 465 with SSL, 587 with TLS.
  • Publish SPF, DKIM and DMARC for the domain in your From address. Gmail has been rejecting non-compliant mail more often since November 2025.
  • If only invoices and reminders are missing, the cron is the likely cause, not the mail settings.
  • Many cloud hosts block outbound SMTP ports. A transactional provider on port 2525 or an API-key mail provider gets around the block.

How do I find out why a WHMCS email didn't send?

WHMCS records outgoing client email in the Email Message Log and records sending errors in the Activity Log, both at Configuration > System Logs in WHMCS 8.13 and 9.x. Read them in this order:

  1. Open the Email Message Log and search for the client or subject. If the message isn't there, WHMCS never tried to send it, so look at the cron, the template and any hooks.
  2. Open the Activity Log and look for an error logged at the time of the send attempt.
  3. If the message is in the Email Message Log and the Activity Log shows no error, the message left WHMCS without an error from your mail server. WHMCS's troubleshooting docs treat that as a delivery problem on the recipient's side, so go to the SPF, DKIM and DMARC section below.
  4. Once the cause is fixed, use Resend on the Emails tab of the client's profile.

Three templates are never logged, to protect their data: Automated Password Reset, Client Email Address Verification and Password Reset Validation.

The error text in the Activity Log points straight to the cause:

Error in the Activity LogWhat it meansWhere to fix it
Could not instantiate mail functionPHP Mail is selected and the server rejected the mail() callFix 1
SMTP connect() failed or Could not connect to SMTP hostWrong host, port or SSL type, a firewall rule, or a blocked portFix 1 and Fix 5
Could Not AuthenticateThe SMTP server rejected the username or passwordFix 1
Sender Verify FailedThe From address doesn't exist on the SMTP serverUse a real mailbox as the From address
Email Send Aborted By HookA custom hook stopped the emailFix 4
Email sending aborted by configurationDisable Email Sending is set to ONSet it to OFF on the Mail tab
Smarty Error: Not allowed by security policyThe template uses code the email security policy blocksFix 4
No recipients provided for messageThe client opted out of that type of emailCheck the client's email notification preferences

Fix 1: Change the mail provider from PHP Mail to SMTP

PHP Mail is the default WHMCS mail provider and the most common reason WHMCS email fails or lands in spam, because many receiving servers treat PHP mailer scripts as unverified mail. WHMCS's own spam troubleshooting starts with switching to SMTP. The setting is in the same place in WHMCS 8.13, 9.0 and 9.1:

  1. Go to Configuration > System Settings > General Settings and open the Mail tab.
  2. Next to Mail Provider, click Configure Mail Provider.
  3. Choose SMTP, or one of the built-in providers: Google, Microsoft, Mailgun, SendGrid or SparkPost.
  4. For SMTP, enter the hostname, port, SSL type, username and password your mail provider gives you.
  5. Click Test Configuration. WHMCS won't save a mail provider configuration unless the test email succeeds.
  6. Click Save Changes.
SMTP SSL TypePort to useHow the connection works
SSL465Encrypted from the first byte
TLS587Starts plain, then upgrades with STARTTLS
None25 or 26Unencrypted and often blocked; avoid it

A mismatch, such as TLS on port 465, produces an SMTP connection error. For more detail, turn on Debugging for the mail provider on the Mail tab, reproduce the problem, read the output in the system logs, then turn debugging off. The full steps are in WHMCS's SMTP setup guide.

Two provider changes catch people out. Microsoft no longer supports basic username-and-password SMTP authentication, so Microsoft 365 needs WHMCS's Microsoft provider with a Microsoft Entra ID app. WHMCS 9.0 removed password authentication for Google, so a Google mailbox that worked on 8.x has to be reconnected with OAuth2 after the upgrade.

Fix 2: Publish SPF, DKIM and DMARC for the sending domain

SPF, DKIM and DMARC are DNS records that prove your server or provider may send for your domain, and Gmail and Yahoo now require them for the domain in the From address. WHMCS uses the Email Address on the General tab of General Settings for client mail, System Emails From Email on the Mail tab for admin notifications, and each support department's own address for ticket mail.

  1. SPF: publish one TXT record that lists every service sending for the domain, for example v=spf1 a mx include:spf.your-provider.example ~all. Use the include value your provider documents, keep a single SPF record, and stay under SPF's limit of 10 DNS lookups.
  2. DKIM: add the selector record your provider or cPanel generates, such as selector1._domainkey.example.com. Google requires keys of at least 1024 bits and recommends 2048.
  3. DMARC: start with v=DMARC1; p=none; rua=mailto:[email protected] at _dmarc.example.com, read the reports for a few weeks, then move to p=quarantine or p=reject.
  4. Reverse DNS: if WHMCS sends from its own server, the sending IP needs a PTR record that resolves to a hostname, and that hostname must resolve back to the same IP.

DMARC passes only when SPF or DKIM passes for a domain aligned with the From address. A provider that signs with its own domain passes DKIM without aligning, so complete the provider's custom domain authentication instead of relying on its defaults.

What do the 2024 Gmail and Yahoo sender rules require?

Google and Yahoo started enforcing sender requirements in February 2024, and Google's sender FAQ says Gmail began ramping up enforcement in November 2025, with temporary and permanent rejections for non-compliant mail. The rules cover mail sent to personal Gmail and Yahoo accounts.

RequirementAll sendersBulk senders (5,000 or more messages a day to Gmail)
AuthenticationSPF or DKIMSPF and DKIM, plus DMARC (p=none is enough)
From domain aligned with SPF or DKIMNot requiredRequired
Valid forward and reverse DNSRequiredRequired
TLS for sendingRequired by GmailRequired by Gmail
Spam complaint rateBelow 0.3%Below 0.3%
One-click unsubscribeNot requiredMarketing and subscribed messages only

Google counts all mail from the same primary domain toward the 5,000 threshold, so a host with a few thousand clients can cross it on a busy invoicing day. Transactional messages such as password resets are excluded from the one-click unsubscribe rule; newsletters sent from WHMCS are not. See Google's email sender guidelines and Yahoo's sender best practices.

Fix 3: Make sure the WHMCS cron is running

Most billing emails in WHMCS are created by the system cron, so a stopped cron looks like broken email. Invoice creation, unpaid and overdue reminders, domain renewal notices and suspensions all run as cron tasks such as --CreateInvoices, --InvoiceReminders and --DomainRenewalNotices. If order confirmations and ticket replies arrive but invoices don't, check the cron before touching the mail settings:

  1. Go to Utilities > Automation Status. A yellow badge means the cron hasn't run in two hours; a red one means it has never run or the daily tasks failed in the last 24 hours.
  2. Search the Activity Log for entries starting with Cron Job. The last entry each day should be Cron Job: Completed.
  3. Compare your cron line with the command shown at Configuration > System Settings > Automation Settings, for example */5 * * * * php -q /home/username/crons/cron.php.

WHMCS 9.0 and later return 403 Access Denied to HTTP requests for crons/cron.php by default, so an external scheduler that calls the cron by URL stops working after the upgrade until you add its IP to Cron HTTP Access Restriction on the Security tab. The full diagnosis is in our guide to fixing a WHMCS cron that isn't running.

Fix 4: Check email templates, welcome email settings and hooks

When one type of WHMCS email never sends while others do, the cause is usually its template, its product settings or a hook.

  • Disabled template: open Configuration > System Settings > Email Templates and check that the template isn't disabled.
  • Syntax errors: the system log records the error and line number. Correct that line in the template and save.
  • Upgrades to 9.x: WHMCS 9.0 moved to Smarty 4.0 and removed the {php}, {fetch} and {include_php} tags, so templates customized years ago can break after the upgrade. Our WHMCS 9 upgrade service includes these template fixes.
  • Welcome emails: a product welcome email sends only after the module's Create command succeeds. Products with no server module need the Auto Release module, and the product's Details tab must have a welcome email selected.
  • Hooks: custom code in /includes/hooks or /modules/addons can cancel mail at the EmailPreSend hook point. Turn on Hooks Debug Mode on the Other tab of General Settings, reproduce the send, and the Activity Log names the hook file.

Fix 5: Check whether your host blocks outbound SMTP ports

Cloud providers block outbound mail ports to stop spam, and WHMCS then shows an SMTP connection error even when the settings are correct. At the time of writing (November 2026):

  • DigitalOcean blocks ports 25, 465 and 587 on Droplets and recommends a third-party email service (DigitalOcean docs).
  • Hetzner Cloud blocks ports 25 and 465 by default and leaves 587 open; unblock requests are reviewed case by case after your first month and first paid invoice.
  • Amazon EC2 throttles port 25 by default.
  • cPanel servers with SMTP Restrictions turned on in WHM's Security Center stop WHMCS from reaching an external SMTP server.

Test from the WHMCS server with nc -vz smtp.example.com 587 or openssl s_client -connect smtp.example.com:465. If the connection times out, use an open alternative port, such as 2525 on Mailgun, Postmark and SendGrid or 2587 on Amazon SES, or use one of WHMCS's API-key providers (Mailgun, SendGrid or SparkPost), which authenticate with an API key instead of an SMTP login.

Fix 6: Send through a transactional email provider

A transactional email provider gives WHMCS a sending reputation and DKIM signing that a shared or newly built server doesn't have, which makes it the most dependable long-term fix. All four below work with WHMCS over SMTP, and Mailgun and SendGrid also have built-in WHMCS mail providers.

ProviderHow to connect in WHMCSSMTP hostPorts
Amazon SESSMTP, using SMTP credentials created in SESemail-smtp.<region>.amazonaws.com587 or 2587 (TLS), 465 or 2465 (SSL)
PostmarkSMTP, with the Server API token as both username and passwordsmtp.postmarkapp.com587, 2525 or 25 with STARTTLS
MailgunBuilt-in Mailgun provider (region, sending domain, API key) or SMTPsmtp.mailgun.org587 or 2525 (TLS), 465 (SSL)
SendGridBuilt-in SendGrid provider (API key) or SMTP with the username apikeysmtp.sendgrid.net587 or 2525 (TLS), 465 (SSL)

Verify your sending domain with the provider before you switch WHMCS over, so its DKIM signature aligns with your From address. If you use a SendGrid Restricted Access API key, WHMCS needs all of SendGrid's Mail Send and Mail Settings permissions.

Frequently asked questions

Why does WHMCS show an email as sent when the client never got it?

The email left WHMCS, but the receiving server filtered or rejected it. If the message is in the Email Message Log and the Activity Log shows no error, check SPF, DKIM and DMARC for the From domain, whether your sending IP is on a blacklist, and the recipient's spam folder.

Which SMTP port should WHMCS use?

Use 587 with the TLS setting or 465 with the SSL setting, whichever your provider supports. If your host blocks both, Mailgun, Postmark and SendGrid accept port 2525, and Amazon SES accepts 2587 and 2465.

Do WHMCS invoice emails need a one-click unsubscribe link?

No. Google's sender FAQ excludes transactional messages from the one-click unsubscribe requirement. Newsletters and promotions sent from WHMCS do need it once you send 5,000 or more messages a day to Gmail accounts.

Why did WHMCS emails stop after upgrading to 9.0?

The usual causes are custom templates that use Smarty tags 9.0 removed, a Google mail provider still set to password authentication, which 9.0 no longer supports, and an HTTP-triggered cron that 9.0 blocks by default. The Activity Log shows which one you have.

Can I send WHMCS email through Gmail or Microsoft 365?

Yes, through WHMCS's built-in Google or Microsoft mail provider, both of which use OAuth. Mailbox providers apply daily sending limits, so a transactional provider is a better fit once you send thousands of invoices and reminders a month.

If you'd rather hand this off, our WHMCS email deliverability fix sets up SPF, DKIM, DMARC and reverse DNS for your sending domain. For renewal reminders that shouldn't depend on email alone, the Multi-Channel Notifications module sends WHMCS events by SMS, WhatsApp or Telegram as well as email.