WHMCS Email Templates: Edit, Brand and Test Them Safely

Where do WHMCS email templates live?

At Configuration > System Settings > Email Templates, with the branding that wraps around them set elsewhere. That split is what people get wrong: the words are in the template, the logo and colors are not. The Email Templates page documents the editor itself, and the Mail tab page the global settings below.

One restriction matters before you start: you cannot change the sender or subject on support ticket templates. They keep a fixed format so email piping can match replies back to the right ticket.

How do you stop a test email reaching real clients?

Set Disable Email Sending to ON in the Mail tab before you touch anything. WHMCS then sends no outgoing mail at all, which is what you want while a half-edited template could still fire from a cron run or a client action. The Disable Outgoing Mail page names testing customizations as the intended use, and says to turn it off again as soon as you are done, because payment reminders and purchase confirmations stop with everything else.

WHMCS logs an entry at Configuration > System Logs whenever that setting changes, so you can see when it went on. SparkPost users also have Use Sink Testing, which checks sending without delivering. Better still, work on a staging copy, as in my WHMCS invoice template guide.

How do you edit a WHMCS email template?

Click the template name or its edit icon, change what you need, save. The Customize Email Templates page walks the editor section by section:

1. Header information. Sender name and address, CC and BCC as a comma-separated list, and a toggle to send as plain text.
2. Attachments. Choose Files, then Add More for a second file. WHMCS uploads them to your downloads directory, so a large PDF on a busy template costs disk; the documentation suggests an Amazon S3 bucket when that space runs short.
3. Subject. Free text, except on support ticket templates.
4. Body. Enable/Disable Rich Text Editor switches between the visual editor and raw HTML. Do the real work in HTML view: it is easy to lose a Smarty tag in the rich text editor.

You can add your own with Create New Email Template, but only in the four types you can send by hand: General, Product, Domain and Invoice. Use a name no other template has, because only admins see it and you will pick it from a menu later. Never call one Mass Mail Template: WHMCS reserves that name and deletes any template using it after a mass mail runs.

Product messages add a rule. A custom welcome, termination or upgrade email must be created in the Product/Service Messages category or it will not appear in the product's menus. You then assign it per product: Welcome Email on the Details tab, Termination Email on the Pricing tab, Upgrade Email on the Upgrades tab. See Assign Custom Emails to Products.

Which merge fields can you put in the body?

The list under the editor window is the only list that matters, because the fields change with the type of template open: an invoice template offers invoice data, a ticket template offers ticket data. Clicking a field's description inserts it. These are the patterns that list does not make obvious:

That last one prints custom fields without naming each of them:

{foreach from=$service_custom_fields item=customfield}
{$customfield}
{/foreach}

Smarty conditionals work too, so one template can cover two cases instead of becoming two templates. The documentation's own example adds a line to a ticket confirmation for one department only:

{if $ticket_department eq "Sales"}
The sales department is open 9-5pm Monday-Friday. We thank you for your patience.
{/if}

WHMCS recommends avoiding {php} tags in email templates for security reasons. Where a message genuinely needs logic, the documented route is a hook.

How do you brand every WHMCS email at once?

Edit the three global boxes in the Mail tab rather than every template. Global Email Header Content and Global Email Footer Content hold the HTML that wraps each message; Global Email CSS Styling holds the stylesheet that formats it. Change those once and every client email changes.

The Configure Email Styling page publishes the exact defaults, worth reading before you replace them. The shipped header is an XHTML document with an [EmailCSS] placeholder in its style block, a logo linked to your company domain, and a container table that the stylesheet fixes at 600 pixels wide. The stylesheet carries the usual email client workarounds, including a mobile breakpoint at 640 pixels with a hide-mobile class.

Two limits to plan around. Admin notification emails cannot be styled this way, so order and cron notices stay plain, and a template set to send as plain text carries no HTML for the styling to wrap. Where branding goes further than a logo and colors, that is theme-level work, which I cover on my WHMCS theme customization page.

How do you send one template in several languages?

Activate the locale first, then translate. On the template list, click Manage Languages, pick the locale under Choose language to add and click Activate. Editing a template then shows an extra subject and body editor for that locale below the default one, as Localize Email Templates explains.

What gets sent follows a clear order. Editing without activating anything changes the default version, which goes to your default locale and every locale you have not translated. Where a translation exists for the client's preferred locale, that version goes instead. The language comes from the Summary tab of the client profile; individual users use the language at Clients > Manage Users; admin emails use the system default from the Localization tab, falling back to English if that language is invalid or deleted.

How do you add data that WHMCS does not already hold?

With a hook file in /includes/hooks, not with PHP inside the template. Four hook points in the WHMCS hooks reference cover almost everything people try to do to email.

The first two are usually written together: one supplies the value, the other shows the field name to whoever edits that template next. My WHMCS hooks guide covers how hook files load.

How do you test an email template safely?

Send it to yourself from a test client, then prove it left by reading the log. The mail provider and the template are separate things to check, in that order. For the provider, use Test Configuration in the Mail tab; WHMCS also sends a test when you save a provider and refuses to save unless that test succeeds. SMTP adds a Debugging toggle for connection problems.

For the template, create a client whose email address is yours. On that client's Summary tab, Load Message opens an existing template to send and New Message composes a one-off; invoice emails go out from the invoice at Billing > Invoices. Anything already sent can go again: find it in the client's Email tab or the Email Message Log, click Resend, edit and send. See Emailing Clients.

Run through this before calling a template change finished:

• Every merge field printed a real value, with no blanks and no literal {$variable} left in the text.
• The message reads correctly as HTML, and as plain text if you use that option.
• The Email Message Log shows the send and the Activity Log shows no error at that time.
• The template is not left checked as Disable.
• Disable Email Sending is back to OFF in the Mail tab.
• Any product whose welcome, termination or upgrade email you changed still has the right template selected.

The log has blind spots. The documentation says it holds back messages from templates that carry sensitive data, and names three: Automated Password Reset, Client Email Address Verification and Password Reset Validation. A separate rule stops CC and BCC on Password Reset Validation, Password Reset Confirmation and Automated Password Reset. Testing a password email means watching an inbox, not the log.

One rule from the Unsent General Emails page saves hours. If a message appears in the Email Message Log and no error appears in the Activity Log, it left WHMCS cleanly and the problem is delivery, not your template. That is a mail server and DNS question: my DMARC setup guide and my notes on cPanel email going to spam start there.

In words: wrong wording in one message means edit that template. A change that belongs on every message means the global header, footer or CSS. Another language means activating the locale and translating there. Text needing data WHMCS does not hold means an EmailPreSend hook. If none fit and the template is broken, restore the defaults.