Configure SMTP mail in WHMCS so emails reach the inbox

Invoices, password resets and welcome emails are useless if they land in spam. By default WHMCS can use PHP Mail, which sends without authentication and is often filtered. Switching to authenticated SMTP from a real mailbox on your domain fixes most delivery problems.

Before you start

• A mailbox on your domain to send from, for example billing@example.com, created in cPanel or your mail provider.
• Its SMTP server, port, user name and password (or a Google Workspace / Microsoft 365 account for OAuth).
• SPF and DKIM set up for the domain, for example via email authentication in cPanel.

Open the mail settings

1. Go to Configuration → System Settings → General Settings.
2. Open the Mail tab.
3. Click Configure Mail Provider.

Option A: SMTP

1. Choose SMTP as the Mail Provider.
2. Enter the settings:
   • Hostname – for cPanel hosting usually mail.example.com or the server hostname.
   • Port – 465 with SSL, or 587 with TLS.
   • Username – the full email address.
   • Password – the mailbox password.
   • SMTP Debug – leave off unless troubleshooting.
3. Click Test Configuration. WHMCS reports success or the server's error message.
4. Click Save.

Option B: Google or Microsoft (OAuth)

1. Choose Google or Microsoft as the provider.
2. Create an OAuth app in Google Cloud Console or Microsoft Entra ID as described in the WHMCS screen, and enter the Client ID and Client Secret.
3. Use the redirect URL WHMCS shows.
4. Click Connect, sign in to the mailbox and approve. Then test and save.

OAuth avoids storing a mailbox password and keeps working when providers disable basic SMTP authentication.

Set the sender details

On the same Mail tab, set System Emails From Name and System Emails From Email to match the SMTP mailbox, for example Example Billing and billing@example.com. A From address on a different domain than the SMTP account causes SPF and DMARC failures.

Check sent emails

Utilities → Logs → Email Message Log lists every message WHMCS sent, with recipient and content. Failures are recorded in Utilities → Logs → Activity Log with the SMTP error.

Troubleshooting

• SMTP Error: Could not authenticate: wrong user name or password, or the mailbox requires an app password (Google, Microsoft with MFA).
• Connection timed out: the port is blocked by the WHMCS server's firewall. Try 587 or 465; many hosts block outgoing port 25.
• Certificate errors: use the hostname that matches the mail server's SSL certificate, often the server hostname rather than mail.example.com.
• Emails accepted but land in spam: check SPF, DKIM and DMARC; send a test to Gmail and use Show original.
• Some clients receive nothing: their email address bounces. Check the mailbox you send from for bounce messages.

Next steps

• Customise WHMCS email templates.
• Set up support departments and email piping.
• Create a mailbox in cPanel.