Email Templates

From WHMCS Documentation

The email templates allow you to customise the messages that go out to your customers when actions occur inside WHMCS. Every email that goes out to a customer can be customised here.

To edit an email template, go to Setup > Email Templates and click the edit icon next to the template you want to change.

You can also toggle plain text vs. HTML email sending on a per email basis from the editor page.

Note:
The subject of the email support ticket email templates cannot be modified. This is because they need to be in a specific format in order for the email piping feature to import email replies into the ticket system.

Creating Custom Templates

You can create your own email templates to serve as custom welcome emails for products or messages you send manually but frequently

  1. To do that use the Create New Email Template area at the top of the page.
  2. You can only create email templates for the types you can manually send: General, Product, Domain & Invoice.
  3. You should use a unique name for the template so you can identify it in the send message dropdowns. Only admin users will see the name you give it.
  4. You'll be taken to the editor interface to compose the email subject and message.

Now the email will be listed in the appropriate place for sending. Please refer to the Messages/Emails page.

Note:
The email template name "Mass Mail Template" is reserved for use by WHMCS when sending a mass mail. Any email template you create with this name will be removed after you send a mass mail, so using this name is not recommended.

Adding an Attachment

An email template can contain attachments that will be included each time that particular email is sent to clients. Simply navigate to Setup > Email Templates and click the Edit icon next to the appropriate email template.

Then browse to the file on your computer you wish to be attached. Click the Add More link if you wish to attach more than one file. Upon clicking Save Changes the file(s) will be uploaded to your downloads directory.

Adding Headers and Footers

It's possible to configure a universal header and footer to be used in all email templates. The header will be displayed at the top of every email template sent by the system whilst the the footer will be displayed at the bottom of every email. These can be configured under Setup > General Settings > Mail tab and as a result the email templates are formed of the following different elements as below:

Global Email CSS Styling

Global Email Header Content

Email Template Content

Global Email Signature

Global Email Footer Content


Disabling Templates

There may be circumstances where you want to disable certain emails from sending. For example you might not want emails to go out when invoices get created, or when a product is suspended.

You can do that by following these steps:

  1. Edit the email template you wish to disable
  2. Check the Disable tickbox in the fields at the top of the page
  3. Save your changes to the email

That email will now not send until re-enabled.

Translating Email Templates

The default version under Setup > Email Templates > Edit corresponds to the language you have selected in Setup > General Settings > Localisation tab. You can translate the email templates and WHMCS will send emails in that language if the client chooses it during the order process:

  1. At the bottom of the Setup > EMail Templates page select the language you wish to add from the Add dropdown menu
  2. Edit each email template and a second text area will appear
  3. Translate the email template into the selected language

That's all there is to it. Clients who choose that language will now receive the translated emails.

Merge Fields

In email messages you can enter merge field variables which are then replaced at the time of sending automatically with the users data.

The merge fields available in your message depend on what type of email you are sending. For example if it's an email related to a client you can include client fields only, but if it's a product related email you could include product details as well as client fields.

The exact list of fields you have available in any email message you are composing are listed directly below the message box with the field description and merge field code. Clicking on the description will insert the merge field at the point of your cursor in the message.

Addon Merge Fields

  • To display the Addon name in the welcome email, you can reference this using the format {$addon_name}.

This will now allow you to send the name of the Addon the client purchased in your Welcome Emails for products.

Custom Fields

Custom fields can also be displayed in emails by way of merge fields.

Custom Client Field

  • To display custom client fields in the email templates, you can reference it by name using the format {$client_custom_field_fieldnamehere}.
  • For fieldnamehere, you need to take your custom field name, convert the name to lowercase and remove anything other than a-z 0-9 chars. For example "VAT Number" would become "vatnumber" once the space was removed, so the merge field would be {$client_custom_field_vatnumber} in the email template.

Product Custom Fields

  • The same applies to Product custom fields, however they are referenced by {$service_custom_field_fieldnamehere}.
  • To loop through and display all the custom fields that apply to a product, you can use a foreach loop like this:
{foreach from=$service_custom_fields item=customfield}
{$customfield}
{/foreach}

Conditional Displays

There may be cases where you want to display text in an email only if certain conditions are met. For example you might want to include specific information in a sales support ticket submission so could use the below conditional statement in the Support Ticket Opened email template:

{if $ticket_department eq "Sales"}The sales department is open 9-5pm Monday-Friday so you
will only receive a response between these times. We thank you for your patience.{/if}

More information: https://www.smarty.net/docsv2/en/language.function.if.tpl

Custom PHP Logic

We recommend against placement and use of the {php} tags in your custom email templates for security reasons. However, if you feel the need for it, we recommend using the EmailPreSend hook point to create your own Smarty merge fields that will run your custom PHP logic. You can reference this via the provided link https://developers.whmcs.com/hooks-reference/everything-else/#emailpresend.

Further Customisation

The email templates are in fact smarty template files so can take advantage of the full range of smarty syntax, just like the .tpl files which control the appearance of the system. More information can be found at https://developers.whmcs.com/themes/variables/.