Important

You are browsing the documentation for version 3.1 of OroCommerce, OroCRM and OroPlatform, which is no longer maintained. Read version 5.1 (the latest LTS version) of the Oro documentation to get up-to-date information.

See our Release Process documentation for more information on the currently supported and upcoming releases.

Available in OroCRM Available in OroCommerce

Configure Email Templates in the Back-Office

With the Oro applications, you can easily send numerous personalized emails using one template. For example, you can make a single template that welcomes {username}, assign it to an email campaign, and each of your subscribers will get a mail sent specifically to them.

Create a New Email Template

  1. Navigate to System > Emails > Templates.

  2. Click Create Template.

    A template creation page
  3. Define the general settings for the template.

    The following fields are mandatory and must be defined:

    • Template Name — Name used to refer to the template in the system.

    • Type — Use html or plain text.

    • Owner — Limits the list of users that can manage the template, subject to the access and permission settings.

    Optional field Entity Name is used to define an entity, variables whereof can be used in the template. If no entity name is defined, only system variables are available.

    Important

    If you want to use the template for autoresponses, the Entity Name field value should be Email.

  4. Define the email template. Click on the necessary variable to add it to the text box.

    A sample of an email template

    Note

    In the example below, the template contains a link to the website page composed with a piece of tracking code. Every time a user follows the link, visit event will be tracked for the campaign.

  5. Click Preview to check your template.

    Preview of an email template
  6. Click Save if you are satisfied with the preview.

Note

You can delete , edit , and clone email templates on the page of all templates.

View a list of templates with three options available: edit, clone, delete

Important

Keep in mind that the ability to view, edit, clone, or delete email templates depends on specific roles and permissions defined in the system configuration. For more information about available access levels and permissions, see the Understand Roles and Permissions guide.

Hint

If you want to track the user-activity related to the emails sent within the email campaign, add a piece of tracking website code to the email template.

View Available Template Variables and Functions

For the security reasons, the only available variables are currently the ones listed on the Email Templates edit page in the back-office. However, there are a few exceptions. These are several Twig functions enabled in email templates that can be used to obtain some specific data in email templates.

The full list of these functions is the following:

Important

Keep in mind that when editing HTML email templates, you pass them to the WYSIWYG editor. WYSIWYG automatically tries to modify the given HTML template against the HTML specifications. Therefore, the text and tags that violate the HTML specifications should be wrapped up in the HTML comment. For example, there should not be any other tags or text between the <table></table> tags except thead, tbody, tfoot, th, tr, td.

Examples:

Invalid template:

 1 <table>
 2     <thead>
 3         <tr>
 4             <th><strong>ACME</strong></th>
 5         </tr>
 6     </thead>
 7     {% for item in collection %}
 8     <tbody>
 9         {% for subItem in item %}
10         <tr>
11             {% if loop.first %}
12             <td>{{ subItem.key }}</td>
13             <td>{{ subItem.value }}</td>
14             {% endif %}
15         </tr>
16         {% endfor %}
17     </tbody>
18     {% endfor %}
19 </table>

Valid template:

 1 <table>
 2     <thead>
 3         <tr>
 4             <th><strong>ACME</strong></th>
 5         </tr>
 6     </thead>
 7     <!--{% for item in collection %}-->
 8     <tbody>
 9         <!--{% for subItem in item %}-->
10         <tr>
11             <!--{% if loop.first %}-->
12             <td>{{ subItem.key }}</td>
13             <td>{{ subItem.value }}</td>
14             <!--{% endif %}-->
15         </tr>
16         <!--{% endfor %}-->
17     </tbody>
18     <!--{% endfor %}-->
19 </table>

Functions

date

1date()

Description: Converts an argument into a date to allow date comparison.

Example: See the Twig doc

oro_config_value

1oro_config_value(string $configSettingName)

Description: Returns the Oro config setting value.

Returns: string

Example: Accessing Configuration Values in Templates

calendar_date_range

1calendar_date_range(
2    \DateTime $startDate = null,
3    \DateTime $endDate = null,
4    $skipTime = false,
5    $dateType = null, \\IntlDateFormatter constant or it's string name
6    $timeType = null, \\IntlDateFormatter constant or it's string name
7    $locale = null,
8    $timeZone = null
9)

Description: Returns a string that represents a range between $startDate and $endDate, formatted according the given parameters.

Returns: string

  • $endDate is not specified
    • Thu Oct 17, 2013 - when $skipTime = true

    • Thu Oct 17, 2013 5:30pm - when $skipTime = false

  • $startDate equals to $endDate
    • Thu Oct 17, 2013 - when $skipTime = true

    • Thu Oct 17, 2013 5:30pm - when $skipTime = false

  • $startDate and $endDate are the same day
    • Thu Oct 17, 2013 - when $skipTime = true

    • Thu Oct 17, 2013 5:00pm – 5:30pm - when $skipTime = false

  • $startDate and $endDate are different days
    • Thu Oct 17, 2013 5:00pm – Thu Oct 18, 2013 5:00pm - when $skipTime = false

    • Thu Oct 17, 2013 – Thu Oct 18, 2013 - when $skipTime = true

Example:

1calendar_date_range(entity.start, entity.end, entity.allDay, 'F j, Y', 1)

calendar_date_range_organization

 1calendar_date_range_organization(
 2    \DateTime $startDate = null,
 3    \DateTime $endDate = null,
 4    $skipTime = false,
 5    $dateType = null, \\IntlDateFormatter constant or it's string name
 6    $timeType = null, \\IntlDateFormatter constant or it's string name
 7    $locale = null,
 8    $timeZone = null,
 9    OrganizationInterface $organization = null
10)

Description: The same as ‘calendar_date_range’ but for a specific organization.

Returns: string

get_event_recurrence_pattern

1get_event_recurrence_pattern(Entity\CalendarEvent $event)

Description: This method is aimed at showing text description of a recurring event in email invitations.

Returns: string

Example:

1<!--{% if get_event_recurrence_pattern(entity) %}-->
2    <tr>
3        <td style="width: 65pt; padding: 0 5pt 0 9pt; line-height: 1.3em; font-family: Arial, Helvetica, sans-serif; font-size: 10pt; vertical-align: top"><strong>Repeats:</strong></td>
4        <td style="padding: 0 9pt 0 0; line-height: 1.3em; font-family: Arial, Helvetica, sans-serif; font-size: 10pt; vertical-align: top">{{ get_event_recurrence_pattern(entity) }}</td>
5    </tr>
6<!--{% endif %}-->

website_path

1website_path(string $route, array $routeParams, Website|null $website = null)

Description: Returns the absolute path for a specific route and parameters.

Returns: string

Example:

1<p>Please follow this link to confirm your email address: <a href="{{ website_path('oro_customer_frontend_customer_user_confirmation', {'username': entity.username, 'token': token}, entity.website) }}">Confirm</a></p>

website_secure_path

1website_secure_path()

Description: The same as ‘website_path’ but returns Secure (HTTPS) URL.

url

1    url()

Description: Returns the absolute URL (with scheme and host) for the given route.

Example: See the Symfony Twig Extensions (URL)

path

1    path()

Description: Returns the relative URL (without the scheme and host) for the given route.

Example: See the Symfony Twig Extensions (Path)

get_payment_methods (OroCommerce Only)

1get_payment_methods(Order $entity)

Description: Returns the allowed payment methods for orders.

Returns: array of OroBundlePaymentBundleTwigDTOPaymentMethodObject objests with payment method label and options (can be used as array of strings thanks to PaymentMethodObject::__toString method)

Example:

1    {% set payment_methods = get_payment_methods(entity) %}
2
3    <!--{% if  payment_methods|length == 1 %}-->
4        <h4>Payment Method:</h4>
5        <!--{{ payment_methods[0] }}-->
6    <!--{% elseif payment_methods|length > 1 %}-->
7        <h4>Payment Methods:</h4>
8        <!--{{ payment_methods|join(', ') }}-->
9    <!--{% endif %}-->

Alternative example:

 1{% set payment_methods = get_payment_methods(entity) %}
 2{% if  payment_methods|length == 1 %}
 3    <strong>Payment Method: </strong>
 4{% elseif payment_methods|length > 1 %}
 5    <strong>Payment Methods: </strong>
 6{% endif %}
 7{% for payment_method in payment_methods %}
 8    {{ payment_method.label }}
 9    {% if payment_method.options|length > 0 %}
10        {{- ' (' ~ payment_method.options|join(', ') ~ ')' -}}
11    {% endif %}
12    <br/>
13{% endfor %}

get_payment_status_label (OroCommerce only)

1get_payment_status_label(Order $entity)

Description: Returns the translated label for the payment status. See the \Oro\Bundle\PaymentBundle\Formatter\PaymentStatusLabelFormatter::formatPaymentStatusLabel method for details.

Returns: string

Example: See an example for the get_payment_status (OroCommerce only) method.

get_payment_status (OroCommerce only)

1get_payment_status(Order $entity)

Description: Returns the payment status for requested order.

Returns: string, one of OroBundlePaymentBundleProviderPaymentStatusProvider class statuses (‘full’, ‘partially’, ‘invoiced’, ‘authorized’, ‘declined’, ‘pending’)

Example:

1<strong>Payment Status: </strong>{{ get_payment_status_label(get_payment_status(entity)) }}

oro_order_shipping_method_label (OroCommerce only)

1oro_order_shipping_method_label(string $shippingMethod, string $shippingMethodType)

Description: Returns the translated label of the order`s shipping method.

Returns: string

Example:

1{% set shipping_method = oro_order_shipping_method_label(entity.shippingMethod, entity.shippingMethodType) %}
2<strong>Shipping Method: </strong>{{ shipping_method }}<br/>

rfp_products (OroCommerce Only)

1rfp_products(Oro\Bundle\RFPBundle\Entity\Request $entity)

Description: Returns a list of products requested by a buyer in this request for quote.

Returns:

 1array: [
 2    345 => [ \\Product ID
 3        'name' => 'Yarn', \\ string, Product name
 4        'sku' => 'YRN345erer', \\ string, Product SKU
 5        'comment' => 'Most interesting product for us', \\ string, Comment in RFP for this product
 6        'items' => [ \\array, Requested product items
 7            38473 => [ \\Product Item ID
 8                'quantity' => 49.86, \\ float, Product Item quantity
 9                'price' => $price, \\ \Oro\Bundle\CurrencyBundle\Entity\Price object, Product Item price
10                'unit' => 'ft', \\ string, Product Item unit
11            ],
12            139473 => [ \\Product Item ID
13                'quantity' => 21.98, \\ float, Product Item quantity
14                'price' => $price, \\ \Oro\Bundle\CurrencyBundle\Entity\Price object, Product Item price
15                'unit' => 'item', \\ string, Product Item unit
16            ],
17            ...
18        ],
19    ],
20    ...
21]

Example:

 1{% set products = rfp_products(entity) %}
 2{% if products|length %}
 3    <table style="border: 1px solid black;margin-top: 10px">
 4        <thead>
 5            <tr>
 6                <th><strong>SKU</strong></th>
 7                <th><strong>Product</strong></th>
 8                <th><strong>Quantity</strong></th>
 9                <th><strong>Target Price</strong></th>
10                <th><strong>Comment</strong></th>
11            </tr>
12        </thead>
13        <!--{% for product in products %}-->
14            <!--{% set numItems = product.items|length %}-->
15            <tbody>
16                <!--{% for item in product.items %}-->
17                    <tr>
18                        <!--{% if loop.first %}-->
19                            <td rowspan="{{ numItems }}">{{ product.sku }}</td>
20                            <td rowspan="{{ numItems }}">{{ product.name }}</td>
21                        <!--{% endif %}-->
22
23                        <td>{{ item.quantity }} {{ item.unit }}</td>
24                        <td>{{ item.price ? item.price|oro_format_price : '' }}</td>
25
26                        <!--{% if loop.first %}-->
27                            <td rowspan="{{ numItems }}">{{ product.comment }}</td>
28                        <!--{% endif %}-->
29                    </tr>
30                <!--{% endfor %}-->
31            </tbody>
32        <!--{% endfor %}-->
33    </table>
34{% endif %}

line_items_discounts (OroCommerce only)

1line_items_discounts(Order $entity)

Description: Returns array of discount total sum for every order line item.

Returns: array

1array: [
2    '123123' => [ // Line Item ID
3        'value' => 15.065, \\ float, total sum of discount for the line item
4        'currency' => 'USD', \\ string, Currency of discount
5    ],
6    ...
7]

Example: See an example for order_line_items (OroCommerce only) method.

order_line_items (OroCommerce only)

1order_line_items(\Oro\Bundle\OrderBundle\Entity\Order $entity)

Description: Returns order line items.

Returns:

 1array: [
 2    'lineItems' => [
 3        [
 4            'product_name' => 'Boat', \\ string, Product name
 5            'product_sku' => 'BO1BIG', \\ string, Product SKU
 6            'quantity' => 1.00, \\ float, Product quantity
 7            'unit' => 'item', \\ string, Product unit
 8            'price' => $price, \\ \Oro\Bundle\CurrencyBundle\Entity\Price object, Product price
 9            'comment' => 'Comment for this line Item', string
10            'ship_by' => $price, \\ \DateTime, Line item ship by field
11            'id' => $id, \\ int|string, Line item identifier value
12            'subtotal' => $price, \\\Oro\Bundle\CurrencyBundle\Entity\Price object, Line Item subtotal
13        ],
14        ...
15    ],
16    'subtotals' => [
17        [
18            'label' => 'Shipping', \\ string, Subtotal name
19            'totalPrice' => $price, \\\Oro\Bundle\CurrencyBundle\Entity\Price object, Subtotal Price
20        ],
21        ...
22    ],
23    'total' => [
24        'label' => 'Total', \\ string, label for Total
25        'totalPrice' => $price, \\\Oro\Bundle\CurrencyBundle\Entity\Price object, Total sum Price for all order line items
26    ],
27]

Example:

 1<table style="border: 1px solid black;margin-top: 10px">
 2    <thead>
 3    <tr>
 4        <th><strong>Item</strong></th>
 5        <th><strong>Quantity</strong></th>
 6        <th><strong>Price</strong></th>
 7        <th><strong>Subtotal</strong></th>
 8        <th><strong>Ship By</strong></th>
 9        <th><strong>Notes</strong></th>
10    </tr>
11    </thead>
12    <tbody>
13    <!--{% set data = order_line_items(entity) %}-->
14    <!--{% set lineItemDiscounts = line_items_discounts(entity) %}-->
15    <!--{% for item in data.lineItems %}-->
16        <tr>
17            <td>
18                {{ item.product_name }}
19                <br>
20                SKU #: {{ item.product_sku }}
21                <br>
22            </td>
23            <td>{{ item.quantity|oro_format_short_product_unit_value(item.unit) }}</td>
24            <td>{{ item.price|oro_format_price }}</td>
25            <td>
26                {{ item.subtotal|oro_format_price }}
27                {% set matchedDiscount = lineItemDiscounts[item.id] %}
28                {% if matchedDiscount is not null and matchedDiscount.value > 0 %}
29                    <br/>{{ (-matchedDiscount.value)|oro_format_currency({'currency': matchedDiscount.currency}) }}
30                {% endif %}
31            </td>
32            <td>{{ item.ship_by }}</td>
33            <td>{{ item.comment }}</td>
34        </tr>
35    <!--{% endfor %}-->
36    </tbody>
37</table>

Note

If none of these Twig functions cover your cases, you can create a custom Twig function that returns the desired data that you can use in email templates. Please, see OroEmailBundle documentation for details.

Filters

On top of functions, you can use filters in email templates. The full set of these filters is the following:

Tags

The full set of allowed tags to use in email templates is the following:

Localize Email Templates

To create email templates for different localizations, even the inactive ones, move from tab to tab and create the desired content for required localizations.

Navigating from one language tab to another

To enable the email template fallback to the parent localization, select the Use <localization> (Parent Localization) check box. If the localization does not have a parent, you can enable fallback to the default template value.