Message Templates

Overview

Message templates help to streamline your communications by allowing you to reuse entire emails or parts of emails in both mass mailings and when using the Send Email activity.

There are two categories of Message Templates in CiviCRM:

• User-driven Messages - These are messages created by your staff to communicate with constituents that you want to be able to re-use. Examples include thank-you letters, meeting announcements, etc.
• System Workflow Messages - These are pre-configured messages used by CiviCRM features. Examples include contribution receipts, event registration confirmations.

Creating user-driven templates

The easiest way to create a new message template is to check the Save as New Template box on the message creation screen. This is available both when using the Send Email activity and when sending a mass mailing.

You can also create message templates from scratch or edit existing templates by going to Mailings > Message Templates OR Administer > Communications > Message Templates.

1. Click on Add Message Template.
2. Enter a Message Title and a Message Subject. You can choose to use tokens to personalize your subject line.
3. Scroll down to the HTML Format section and create your template. There are online resources, not specific to CiviCRM, that offer instructions on creating an HTML email templates. One suggestion is to find and copy an email template from a website that offers samples.
4. In the WYSIWYG editor toolbar, there is an icon called "Source" (the appearance and labelling of this icon changes depending on whether you are using Drupal, Joomla, or WordPress). When you click on it, the template changes the view to show the HTML code that is being used. If you want to paste in HTML from a template you found externally, or if you want to write HTML directly into your template or modify the HTML that you've created with the WYSIWYG editor, you need to switch to this view.

Message templates are available even when CiviMail is disabled.

Tips for creating templates

HTML code allowed in emails is more restricted than HTML used for web pages. For instance, it needs to use tables for layout, inline CSS, and must not include background images. Here are some tips for creating a template that will look good in all mail clients:

• Table border: The HTML element includes an optional border attribute. Since the default value is 0, it doesn't appear unless you choose to use it. Adding it (or editing it if it is available) and setting it to 1 (e.g. <table border="1">) allows you to see the edges of your table and helps identify potential places to fix problems. Please note that HTML email templates usually have multiple tables and nested tables (tables inside tables). Make changes one at a time and switch to the HTML view to see the results. A table usually has more than one parameter, so make sure to place spaces between parameters.
  Table cellpadding and cellspacing: these table parameters are very useful when trying to improve the readability of your email. Play with these settings in different tables and see what works for you.
  Width: Do not send an email that is wider than 600 pixels, to ensure maximum compatibility across email clients. Make sure your outermost table does not exceed 600 pixels. Do the same for any other tables inside your main table. Also make sure that the total width of each image does not exceed 600 pixels. Images have a width parameter, but they can also have a horizontal padding parameter that, if set, can increase the width of the image.
  Images: these need to be online and accessible in order for you to use them. First edit your image so that its width and height is appropriate for your email template. Next, save it so that its file size is as small as possible. If you do not have image editing software, or do not know how to use it, there are free online resources that can help you resize your image.
  HTML editor: CiviCRM comes with two WYSIWYG editors (CKEditor and TinyMCE) and Textarea, a plain text editor. If you have another editor configured as part of your Drupal, Joomla, or WordPress installation, you can choose to use that instead. go to: Administer > Customize Data and Screens > Display Preferences and select a different WYSIWYG Editor.

  Plain text and HTML formats

  All messages can be sent either in plain text or in HTML. Today the vast majority of people use email clients that read messages received in HTML.

  It is good practice is to send a plain text email version as well as the html one to ensure all recipients can view the message and there are two ways to make this happen.

  1) (recommended) - ensure the text version of the message is blank. If is is fully empty then during sending a text version will be generated from the HTML version.

  2) enter your text version into the text box on the message template screen. Be warned that it will need to be kept up to date manually. This has a time cost and there is there is a risk that the text version is not maintained over time. This could mean that people using plain text-only email clients will receive an incorrect or incomplete message. This may include people who are visually impaired and using email reading software getting incorrect information if their software prefers the text version.

  To create a plain text version of a message from HTML:

  1. Copy and paste the text from HTML Format field into the Plain Text Format field. When you do this, make sure you are not in the Source view; you don't want all the code, just the text. When you copy from the WYSIWYG view, the plain text field will automatically strip out the formatting and any other elements that do not work in plain text.
  2. Copy the URLs of all links to the appropriate places in the Plain Text Format field.
  3. If the HTML version contained tables, modify the layout of your text manually to ensure the text version is readable.

  Modifying System Workflow Message Templates

  The content and layout of these messages are pre-configured and include program logic to display all the data being sent to your constituents (e.g. contribution amount, payment method, event fees, etc.). Navigate to Administer > Communication > Message Templates and click the System Workflow Message tab to see the list of messages you can modify. Both HTML and Text formats are provided. Your organization may want to modify or add text to these emails, or add branding such as a logo to the HTML versions.

  Your changes here can complicate CiviCRM upgrades

  Occasionally, CiviCRM also makes changes to these system workflow message templates during version upgrades. If you customize a template, CiviCRM will stop applying updates to it. This is good because it preserves your customizations but bad because you might miss out on important template updates as new functionality becomes available.

  The System Administrator Guide provides instructions for merging conflicting edits to these templates (for cases where you have customized the templates and a CiviCRM upgrade would have also made changes to the same template) — but the process is not that easy! So you can save yourself (or your system administrator) some time by avoiding the temptation to edit these templates.

  Don't break anything

  Don't modify the program logic within these templates. Be sure to test the workflow and review the emails sent after making any changes. In most cases, you can restrict your changes to the the top row in the HTML layout. If you find that your changes have caused problems, errors or missing information, you can always revert to the system default for that workflow.

  Use tokens for logo and branding

  As of CiviCRM 5.76, you don't need to edit Message Templates to insert your organization logo or other branding. Instead, use the {site.message_header} Site Token.

  After you have customized system workflow message templates, you can always revert to CiviCRM's version of the template by clicking the "Revert to Default" link which appears next to the template.

  

  Variables and tokens in Workflow message templates

  The workflow message templates can use both tokens and smarty variables. You can tell the difference by the presence of a dollar sign eg.

  {contribution.tax_amount} is a token wheras {$taxAmount} and {$contribution.tax_amount} are both smarty variables. In general tokens are consistent across multiple screens whereas the available smarty variables depend on what has been coded and is highly variable. We are switching to using tokens in workflow message templates where possible but in some cases the variable is very specific to the specific message template or is more complex. We are working to standardise and document the available smarty variables

  As of 5.53 all contribution workflow message templates should support all contact and contribution tokens and the following smarty variables:

  Variable	Meaning	Detail	eg.
  $isShowLineItems	is the contribution using a price set	TRUE or FALSE	{if $isShowLineItems}...{/if}
  $isShowTax	is sales tax enabled for the site	TRUE or FALSE	{if $isShowTax}...{/if}
  $taxRateBreakDown	array of the amount charged at each tax rate.	[] for no tax or	{foreach from=$taxRateBreakdown item=taxDetail key=taxRate}{$taxDetail.percentage}%{/if}{/foreach}

  $lineItem this is an array of line items. Example usage is

    {if $isShowLineItems}
      <tr>
      <td colspan="2" {$valueStyle}>
        <table>
        <tr>
          <th>{ts}Item{/ts}</th>
          <th>{ts}Qty{/ts}</th>
          <th>{ts}Each{/ts}</th>
          {if $isShowTax && '{contribution.tax_amount|raw}' !== '0.00'}
            <th>{ts}Subtotal{/ts}</th>
            <th>{ts}Tax Rate{/ts}</th>
            <th>{ts}Tax Amount{/ts}</th>
          {/if}
          <th>{ts}Total{/ts}</th>
        </tr>
        {foreach from=$lineItems item=line}
          <tr>
          <td>
            {$line.title}
          </td>
          <td>
            {$line.qty}
          </td>
          <td>
            {$line.unit_price|crmMoney:'{contribution.currency}'}
          </td>
          {if $isShowTax && '{contribution.tax_amount|raw}' !== '0.00'}
            <td>
              {$line.unit_price*$line.qty|crmMoney:'{contribution.currency}'}
            </td>
            {if $line.tax_rate || $line.tax_amount != ""}
              <td>
                {$line.tax_rate|string_format:"%.2f"}%
              </td>
              <td>
                {$line.tax_amount|crmMoney:'{contribution.currency}'}
              </td>
            {else}
              <td></td>
              <td></td>
            {/if}
          {/if}
          <td>
            {$line.line_total+$line.tax_amount|crmMoney:'{contribution.currency}'}
          </td>
          </tr>
        {/foreach}
        </table>
      </td>
      </tr>
  
    {/if}
  

  Configure Message Templates

  To configure message templates, begin at the Administer CiviCRM page.

  In the Communications section, choose Message Templates.

  You will see a list of existing templates. If no templates exist, you will see the message:

  There are no Message Templates entered. You can add one.

  Click add one to create a new template.

  You can create NEW message templates or Edit , Preview , Disable or Delete EXISTING message templates using the links to the right of each template.

  NEW

  To create a NEW message template, choose >>New Message Template

  You will be taken to the New Message Template page.

  Create a Message Title for the template. This title is used to organize your messages and will not appear in the email.

  Tokens

  The next three fields can all use tokens to help personalize your messages with things like names, dates and amounts of gifts, etc.

  Here is a list of the tokens you can use

  Create the Message Subject for your email. Use tokens if desired.

  Create your HTML Message. Include tokens to personalize your messages.

  Leave Text Message blank unless you have a strong reason not to.

  Choose Enabled? to enable the message template for use.

  Click Save to save the template or Cancel to cancel.

  If successful, you will see the message:

  "The Message Template "Membership Renewal Initial Message" has been saved."

  EXISTING

  For EXISTING templates you can Edit , Disable or Delete each template using the links to the right of each template.

  EDIT

  Select Edit to view the Edit Template page where you can change the values for each option. Here you can also enable/disable the template by checking or unchecking the box labeled Enabled? at the bottom of the page. Click Save to save the template.

  If successful, you will see the message:

  The Message Template "Membership Renewal Initial Message" has been saved.

  DISABLE

  Select Disable to temporarily disable an Existing Template. You will see the warning:

  "Are you sure you want to disable this Message Template? "

  Click OK to continue or Cancel to cancel disabling the template.

  To re-enable the template, simply click on Enable.

  DELETE

  Select Delete to delete the template. You will be given this warning:

  Do you want to delete this message template?

  Click Delete to continue or Cancel to cancel the deletion.