Setting up order mails

Ticketmatic gives you full control over the layout and content of all transactional order mails. You can use html and css to style the order mails as you like. You can among others:

* include images and logo's * use custom fonts * add headers and footers

You have full control over the content of the order mails. You can make part of the order mails dynamic, dependent on certain conditions. You can among others:

* display dynamic order info like order id, date and total amount, buyer info and order content * display the ticket delivery links * display informational messages or images * display information that is context specific. For example: you can show a specific message if tickets were bought for a specific event or through a specific sales channel.

Order mails can be sent automatically at several important moments in the life cycle of an order:

* when an order is confirmed * when the order tickets should be delivered electronically * when payment instructions need to be sent * when an order is overdue * when an order is expired

This corresponds to the different types of order mails that can be defined:

* confirmation * delivery * paymentinstruction * overdue * expiry

You can have multiple order mails of each type, and deciding which mail to send when is highly configurable. Additionally, order mails can be sent manually from the orders app.

Getting started: set up a new order mail

Order mails are managed in the Settings app. Click the button below to go to the Order mails module:

Go to order mails

Now create a new order mail:

Click on + Add button. A new ticket order mail is now created with default definition.
Go to the Settings tab and fill in name and subject and select a Category. The subject will be used as actual subject when the order mail is sent out. The category defines when the mail will be sent

The <> Definition tab contains the html template for the order mail. This default order mail is empty and is a good base to start customizing.

Preview and testing environment

While you are editing an order mail, you will see the Preview pane on the right displaying your changes in realtime. You can select the example order to test how the order mail looks for that specific order. You can also send a test mail to see how the mail looks in an actual mail client.

Customizing the definition

By editing the definition, you can customize the ticket layout exactly as you want.

Adding static content

Add static content to the order mail by including html/css in the definition.

For example, this definition will create a simple thank you order mail.:

 1<html>
 2    <head>
 3        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 4        <title>Ticketmatic</title>
 5    </head>
 6    <body>
 7       <br>
 8        <center>
 9            <table cellspacing="0" cellpadding="0">
10                <tr>
11                    <td width="3%">
12                        &nbsp;
13                    </td>
14                    <td width="92%" class="content">
15                        
16                        <p>Dear,</p>
17                        <p>Thank you very much for your order.</p>
18                        <p>Kind regards,</p>
19                        <p>Ticketmatic</p>
20                        
21                    </td>
22                    <td width="3%">
23                        &nbsp;
24                    </td>
25                </tr>
26            </table>
27        </center>
28        <br>
29    </body>
30</html>

You see that this is a regular html template, with a head and a body section. In the body section we use a table to position the content of the mail.

Include `` in the head section to avoid problems with special characters like the € sign.

Styling the order mail with CSS

You can use regular css in the head section to style the order mail. Ticketmatic will transform the css in the head section to inline css when sending out the actual order mails to avoid some e-mail clients stripping out <head> and <style> tags from e-mails.

For example, add following tag to the head section to style the previous example:

 1<style type="text/css" media="screen">
 2    body, td, th {
 3        line-height: 1.5;
 4        font-size: 13px;
 5    }
 6    
 7    body {
 8        color: #333;
 9        font-family: Arial, sans-serif;
10        background: #FFF;
11        max-width: 660px;
12        margin: 0 auto;
13    }
14    
15    a,
16    a:link {
17        color: #000 !important;
18        font-weight: 700;
19    }
20    
21    
22    th {
23        text-align: left;
24    }
25    
26    .table {
27        width: 100%;
28    }
29    
30    .table tfoot {
31        font-weight: 700;
32    }
33    
34    .table td,
35    .table th {
36        border-bottom: 1px solid #DDD;
37        padding: 5px;
38    }
39    
40    h1, h2, h3, h4 {
41        color: #000;
42    }
43</style>

Adding dynamic content

Use placeholders to add dynamic content like order id, totalamount or number of tickets. When you build the order mail, you have an several objects at your disposal that contain information about the order. The order mail definition is actually a twig-template and you can use the features of this template language to create a truly dynamic order mail. More info on the Twig template language.

Some example placeholders:

Placeholder	Description
{{order.id}}	The id of the order
{{order.totalamount}}	Totalamount for the order
{{order.createdts	date(“d/m/Y”)}}

Twig filters, like the date filter in the example above, allow you to modify object properties and can be used among others to format properties. More info on the available Twig filters

Click on the (?) Placeholders button to retrieve a list of all objects and properties that you can use as placeholder in the html template. You will get a json-representation of the available object with the current preview-values filled in.

The placeholders also contain collections of items. For example the events placeholder is a collection of all events for which there are tickets in the order. You can use the for loop in twig to loop over all events. The example below shows how to use this to add a table that displays the number of tickets per event in the order:

 1<table class="table" cellspacing="0" cellpadding="0">
 2    <thead>
 3        <tr>
 4            <th translate>Date</th>
 5            <th translate>Event</th>
 6            <th translate>Number</th>
 7            <th translate>Subtotal</th>
 8        </tr>
 9    </thead>
10    <tbody>
11        {% for event in events %}
12        <tr>
13            <td>{{ event.date|date("d/m/Y H:i") }}</td>
14            <td>{{ event.name }}</td>
15            <td>{{ event.ticketsummary.count }}</td>
16            <td>€ {{ event.ticketsummary.price|number_format(2) }}</td>
17        </tr>
18        {% endfor %}
19    </tbody>
20</table>

This is an overview of the placeholders available for an order:

    order 
        <all order placeholders>
    events -> array of event objects with as key the eventid, for each event:
        <all event placeholders>
        tickettypeprices -> array of tickettypeprice objects with as key the tickettypepriceid, for each tickettypeprice:
            tickettypename
            pricetypename
            allocationmethod
            price
            tickets -> array of ticket objects with as key the ticketid, for each ticket:
                <all ticket placeholders>
            ticketsummary
                count
                <aggregate sum value for all numeric ticket placeholders>
        ticketsummary
            count
            <aggregate sum value for all numeric ticket placeholders>        
    ticketsummary
        count
        <aggregate sum value for all numeric ticket placeholders>        
    payments -> array of payment objects, for each payment:
        <all payment placeholders>
    ordercosts
        id
        name
        amount
    buyer
        <all contact placeholders>
    urls
        pdf
        orderdetail
    account
        id
        name
        shortname

Using the `events` placeholder

The events placeholder contains a hierarchical representation of the order contents. This structure allows you to easily display the contents of an order (tickets and/or events) in the level of detail you like. In some cases you only want to show a high level summary of the order, in other cases you want to drill down to the individual ticket level.

There are 3 levels of detail in the object:

events: will contain info aggregated per event
tickettypeprices: will contain info aggregated per tickettypeprice for a specific event
tickets: will contain info on the individual tickets for a specific tickettypeprice for an event

On each level, you will find a ticketsummary object. This object contains the summary data for the specific level you are on.

Let’s look at some examples of how to use this.

If you want to just display one line per event, and the number of tickets per event, you can simply loop over the events object:

1{% for event in events %}
2    {{ event.name }}: {{ ticketsummary.count }} tickets.<br/>
3{% endfor %}

The ticketsummary object contains for all numeric placeholders the sum of the lower levels. So to also display to sum of the prices of the tickets per event:

1{% for event in events %}
2    {{ event.name }}: {{ ticketsummary.count }} tickets, total amount € {{ ticketsummary.price|number_format(2) }}<br/>
3{% endfor %}

If you want more detail, you could display a line for each tickettypeprice per event. If a customer orders 2 Standard tickets and 2 Reduction tickets, he would see 2 lines then. To accomplish this, loop over the events, and use a nested loop over the tickettypeprices:

1{% for event in events %}
2    {% for tickettypeprice in event.tickettypeprices %}
3        {{ event.name }} - {{ tickettypeprice.pricetypename }}: {{ tickettypeprice.ticketsummary.count }} tickets, total amount € {{ tickettypeprice.ticketsummary.price|number_format(2) }}<br/>
4    {% endfor %}
5{% endfor %}

Finally, you could display all the details available and show a single line per ticket. To accomplish this, add another nested loop over the tickets inside the tickettypeprice loop:

1{% for event in events %}
2    {% for tickettypeprice in event.tickettypeprices %}
3        {% for ticket in tickettypeprice.tickets %}
4            {{ event.name }} - {{ tickettypeprice.pricetypename }} - {{ ticket.id }}: total amount € {{ ticket.price|number_format(2) }}<br/>
5        {% endfor %}
6    {% endfor %}
7{% endfor %}

There is also a ticketsummary object on the highest level, so if you simply want to display the number of tickets or another aggregate value for all tickets in the order, use:

1{{ ticketsummary.count }} tickets. Total amount € {{ ticketsummary.price | number_format(2) }}

Using the `urls` placeholder

The urls placeholder contains order specific urls and allows you to link to the actual tickets. Also you can link to the orderdetail page where the buyer can inspect his order online.

The placeholder contains following properties:

Property	Description
pdf	a link to the pdf for all the tickets in the order
orderdetail	a link to the orderdetail page

To include a link to the pdf in an order mail, you can for example use:

1<a href="{{ urls.pdf | raw }}" translate>download your e-tickets as pdf</a>

Note that you should use the raw filter when using the url in an tag to avoid that the url gets escaped. More info on the raw filter

Configuring when to send which order mail

The order mail category defines when an order mail will be sent:

An order mail of category confirmation is sent when an order is confirmed
An order mail of category delivery is sent when an order needs to be delivered electronically
An order mail of category paymentinstruction is sent when an order will not be paid immediately
An order mail of category overdue is sent when the expected payment date of an order is passed
An order mail of category expiry is sent when an order is expired

There can be multiple order mails of each type. The configuration in Delivery Scenario, Payment Scenario and Sales channel determines whether an actual mail will be sent, and which mail will be sent.

Confirmation

For each Sales channel you can configure an order mail of type confirmation in the field Confirmation mail template. This order mail will be sent when an order is confirmed, and can be used as a general ’thank you for your order’ mail. You can check Always send confirmation mail if you always want to send this mail regardless of other order mails that are potentially sent when the order is confirmed. If you uncheck this setting, the confirmation mail will only be sent if no other order mail is sent. The confirmation mail can be re-sent manually from the order page (Actions -> Resend confirmation e-mail).

If you leave the field Confirmation mail template empty, no confirmation mail will be sent.

Delivery

For each Delivery scenario you can configure an order mail of type delivery in the field Mail template. This order mail will be used when the order needs to be delivered.

Note that the Type field should either be E-mail, automatically after payment or E-mail, automatically after confirmation for the order mail to be sent.

Paymentinstruction, overdue and expiry

For each Payment scenario of type Deferred payment you can configure order mails for these types:

in the field Payment instruction mail template for type paymentinstruction. This template will be used when an order with this Delivery scenario is confirmed to send out the payment instructions
in the field Overdue mail template for type overdue. This order mail will be sent when the order becomes overdue (after a configurable number of days)
in the field Expiry mail template for type expiry. This order mail will be sent when the order becomes expired (after a configurable number of days)

Translation

For multilanguage accounts, all text on the order mail can be translated. The order mail will be delivered to the buyer in his preferred language.

In order to translate a text, you should annotate it with a translate attribute. For example:

1<p translate>Some multi-lingual text.</p>

All annotated texts are translatable in the Translate module. Click on translate in the top menu to access this module.

More examples

See here for a complete example of an order mail.