Invoice Email Templates 1.15.41
The invoice email template defines the message that delivers an approved Invoice to the customer. It consists of an email subject, an HTML body and a plain text body, all rendered with Liquid against the data of the invoice being sent.
When an invoice is approved, its PDF document is generated and emailed to the contacts listed in the account's Send invoices to setting, with the document attached. The template is rendered once per invoice — every recipient receives the same message — and the result is recorded in the Email log.
The template is edited at Billing -> Settings -> Invoice email templates.
WARNING
There is a single, system-wide template: it is created automatically, and can be edited but not created or deleted.
Invoice Email Template attributes
- Subject
- The email subject line. A Liquid template, so it can embed variables. Maximum 255 characters.
- Plain text body
- The plain text alternative part of the message.
- HTML body
- The HTML part of the message.
Both bodies are sent together as a multipart message: mail clients show the HTML part, and clients that do not render HTML (as well as the preview panes of many of them) fall back to the plain text part. Keep the two in sync — the plain text body must be readable on its own.
Available variables
A template can reference only the variables below. Anything else is an unknown variable and is rejected when the template is saved.
account and contractor
| Variable | Example | Description |
|---|---|---|
{{ account.id }} | 123 | Account id |
{{ account.name }} | ACME Telecom | Account name |
{{ account.currency }} | EUR | Account currency name |
{{ account.currency_id }} | 978 | Account currency id |
{{ account.balance }} | 1500.00 | Account balance |
{{ account.min_balance }} | 0.0 | Minimal balance threshold |
{{ account.max_balance }} | 100000.0 | Maximal balance threshold |
{{ account.invoice_period }} | Monthly | Invoice period name |
{{ contractor.name }} | ACME Ltd | Contractor name |
{{ contractor.address }} | 1 Example street | Contractor address |
{{ contractor.phones }} | +11234567890 | Contractor phones |
invoice
| Variable | Example | Description |
|---|---|---|
{{ invoice.id }} | 1042 | Invoice id |
{{ invoice.reference }} | invoice-1042 | Invoice reference |
{{ invoice.created_at }} | 2026-08-01T00:00:00+00:00 | When the invoice was created |
{{ invoice.start_date }} | 2026-07-01T00:00:00+00:00 | Begin of the invoice period |
{{ invoice.end_date }} | 2026-08-01T00:00:00+00:00 | End of the invoice period |
{{ invoice.amount_total }} | 1234.56 | Invoice total amount |
{{ invoice.amount_spent }} | 1500.00 | Amount spent by the account |
{{ invoice.amount_earned }} | 265.44 | Amount earned by the account |
Originated (account acts as customer) and terminated (account acts as vendor) traffic summaries have the same structure — invoice.originated.* and invoice.terminated.*:
| Variable | Example | Description |
|---|---|---|
{{ invoice.originated.amount_spent }} | 750.00 | Amount spent for these calls |
{{ invoice.originated.amount_earned }} | 132.72 | Amount earned for these calls |
{{ invoice.originated.calls_count }} | 1000 | Count of calls |
{{ invoice.originated.successful_calls_count }} | 900 | Count of successful calls |
{{ invoice.originated.calls_duration }} | 54000 | Calls duration, in seconds |
{{ invoice.originated.first_call_at }} | 2026-07-01T00:01:00+00:00 | Time of first call |
{{ invoice.originated.last_call_at }} | 2026-07-31T23:59:00+00:00 | Time of last call |
Services summary:
| Variable | Example | Description |
|---|---|---|
{{ invoice.services.amount_spent }} | 30.00 | Amount spent for services |
{{ invoice.services.amount_earned }} | 0.0 | Amount earned for services |
{{ invoice.services.transactions_count }} | 3 | Services transactions count |
service_data and document
service_data is a list of the services billed in this invoice — iterate it with {% for %}:
{% for s in service_data %}
{{ s.service }}: {{ s.transactions_count }} transactions, {{ s.amount }}
{% endfor %}Each row has service (service name), transactions_count and amount.
document describes the attached file:
| Variable | Example | Description |
|---|---|---|
{{ document.filename }} | invoice-1042.pdf | Name of the attached PDF, see Document filename |
Per-destination details are not available
Unlike the invoice PDF template, an email template has no per-destination and per-network breakdowns — an email quotes the totals, the detail belongs to the attached document.
Template syntax
Templates use Liquid: {{ variable }} to output a value, {% if %} / {% for %} for control flow, and | filter to format values. Liquid runs sandboxed, so a template can only touch the variables above — it cannot execute arbitrary code.
Saving a template renders it against sample data first: a syntax error or a variable outside the list above is reported as a validation error, and the template is not stored.
Money values are exact decimal strings, so a bare {% if invoice.amount_total %} is always true — compare explicitly, e.g. {% if invoice.amount_total > 0 %}. Dates and times are ISO-8601 strings; format them with the Liquid date filter:
{{ invoice.end_date | date: "%Y-%m-%d" }}A subject template:
Invoice {{ invoice.reference }} for {{ account.name }}An HTML body is a self-contained HTML fragment:
<table width="100%" cellpadding="0" cellspacing="0" border="0"
style="font-family:Arial,Helvetica,sans-serif;">
<tr>
<td style="background-color:#2c3e50;padding:16px 24px;color:#ffffff;font-size:18px;">
Invoice {{ invoice.reference }}
</td>
</tr>
<tr>
<td style="padding:24px;color:#333333;font-size:14px;">
<p>Dear {{ account.name }},</p>
<p>Please find attached invoice <strong>{{ invoice.reference }}</strong>
covering the period from {{ invoice.start_date | date: "%Y-%m-%d" }}
to {{ invoice.end_date | date: "%Y-%m-%d" }}.</p>
<p>Amount: <strong>{{ invoice.amount_total }} {{ account.currency }}</strong></p>
<p>Attachment: {{ document.filename }}</p>
</td>
</tr>
</table>And the matching plain text body:
Invoice {{ invoice.reference }}
Dear {{ account.name }},
Please find attached invoice {{ invoice.reference }} covering the period
from {{ invoice.start_date | date: "%Y-%m-%d" }} to {{ invoice.end_date | date: "%Y-%m-%d" }}.
Amount: {{ invoice.amount_total }} {{ account.currency }}
Attachment: {{ document.filename }}Email HTML, not web HTML
The HTML body is rendered by mail clients, not browsers. Use inline styles and a table-based layout — <style> blocks, external stylesheets, flexbox and grid are unreliable across clients. Scripts never run: the body is delivered as email and is shown in the admin inside a sandboxed frame.
Preview
Open the template and click Preview to render both parts against sample invoice data in a new tab: the plain text part as text, the HTML part as the mail client would show it. Use it to check the layout before saving.
Delivery failures
A template problem never costs the invoice its email. If a body fails to render at delivery time, the message is still sent — with that part omitted, and the subject falling back to Invoice <id> — and the error is written to the application log. The delivered message, both of its parts and the attachment are recorded in the Email log.