# Overview

Source: https://gokarla.io/docs/platform/email-templates

# Email templates

Karla can email your customers directly using templates you own and manage
inside Karla. Paired with the **Send Karla email** action in Shopify Flow,
this lets any Karla trigger — a delivery issue, a delivered parcel, a new
claim — send a fully branded email without an external email tool in the
middle.

Two pieces work together:

1. **Templates** — email content authored in Karla, with variables that are
   filled in per customer and shipment at send time.
2. **The Flow action** — **Send Karla email** carries the whole event
   payload a Karla trigger provides and sends the email to the recipient you
   choose; Karla fills in the template's variables from that payload.

## How templates are organized

- **Cloned from a catalog** — you don't start from a blank page. Karla ships
  a catalog of ready-made templates covering the common post-purchase
  moments; clone one into your shop and adapt the copy and branding.
- **Organized by tags** — templates carry freeform tags (e.g.
  `delivery-issues`, `returns`, `de`). Tags are purely for organizing and
  filtering your template list — they have no effect on sending.
- **Selected by name** — the Flow action references a template by its
  **name**. Keep names unique and descriptive, and treat them as stable
  identifiers: renaming a template means updating every Flow workflow that
  points at it.

## Template syntax

Variables are written with **double braces** — `{{ variable }}`, not single
braces like `{variable}`. This is plain token substitution, not a template
engine: filters, conditionals, loops, and other Jinja/Liquid features are not
supported, and any `{{ … }}` that isn't a known variable is left unchanged.

```text
Hi {{ customer_first_name }},

good news — your order {{ order_name }} was delivered to your neighbour
{{ neighbour_name }}.

You can review the full delivery history any time:
{{ trackpage_url }}
```

At send time Karla substitutes each variable with the matching value from
the event the Flow action carries. Only use variables that the event you're
reacting to actually provides — for example, `neighbour_name` is only
populated by the delivered-to-neighbour event.

## Variable reference

Template variables are the **curated set Karla exposes for email
templates** — the same list the portal's template editor offers in its
variable picker. Karla substitutes only these tokens; they are the complete
authoring vocabulary.

The [Shipment events](/docs/platform/events/shipments) and
[Claim events](/docs/platform/events/claims) reference documents the
underlying event payloads and is useful background for understanding which
event populates which value — but write your templates with the token names
below, not raw payload field names.

Shipment and order variables:

| Variable                 | Description                                    |
| ------------------------ | ---------------------------------------------- |
| `tracking_number`        | The carrier tracking number.                   |
| `trackpage_url`          | The branded Karla tracking page URL.           |
| `carrier`                | The carrier name.                              |
| `expected_delivery_date` | Estimated delivery date (dd.mm.yyyy).          |
| `updated_at`             | When the shipment or claim was last updated.   |
| `order_name`             | The order name (e.g. #1001).                   |
| `order_number`           | The order number.                              |
| `zip_code`               | Delivery postal code.                          |
| `number_of_shipments`    | Number of shipments in the order.              |
| `pickup_address`         | Pickup point address (parcel shop or locker).  |
| `neighbour_name`         | Name of the neighbour who accepted the parcel. |
| `shipment_id`            | Karla shipment identifier.                     |

Claim variables, populated by the claim events:

| Variable                | Description                                |
| ----------------------- | ------------------------------------------ |
| `claim_id`              | Karla claim identifier.                    |
| `reason`                | The claim reason.                          |
| `resolution_preference` | The customer's preferred claim resolution. |
| `description`           | The customer's claim description.          |
| `created_at`            | When the claim was created.                |
| `image_urls`            | Customer-provided claim image URLs.        |

Customer variables, available across events:

| Variable              | Description                                                |
| --------------------- | ---------------------------------------------------------- |
| `customer_email`      | Customer email address — also the default email recipient. |
| `customer_first_name` | Customer first name.                                       |
| `customer_last_name`  | Customer last name.                                        |

## Set it up in Shopify Flow

### Prerequisites

- The [Karla Shopify app](/docs/guides/shops/shopify) is installed and
  connected to your shop.
- **Karla email notifications are enabled** for your shop. Sending emails
  through Karla is a premium setting — if it is disabled, the action returns
  `403` and the Flow run is marked failed without a retry.
- The referenced **template is active**. An inactive or missing template
  returns `404` and the run fails.

### Create the workflow

1. In Shopify admin, open **Shopify Flow** and create a new workflow.
2. Pick a **Karla trigger** for the moment you want to react to. A curated
   set of shipment and issue triggers is available — e.g. _Delivery Failed_
   or _Delivered to Neighbour_ — covering the most common moments from the
   [Karla event catalog](/docs/platform/events/overview); not every event
   has a Flow trigger. Each trigger exposes the whole event as a single
   **Event data** variable.
3. Add the **Send Karla email** action to the workflow.
4. Fill in the action's three fields:
   - **Event data** — insert the trigger's **Event data** variable. That's
     the only insert needed; there is no per-field mapping.
   - **Recipient** — map the customer's email address, e.g.
     `{{ customer.email }}`. This field is required; if it renders empty at
     runtime, Karla falls back to the event's `customer_email`.
   - **Template name** — type the exact name of the template you cloned and
     adapted in Karla.
5. Activate the workflow and run a test order to verify the rendered email.

:::tip One template, many flows
Because the action selects templates by name, you can reuse the same
template across several workflows — or point different triggers at
different templates for tone-appropriate messaging per event.
:::

## Related

- [Events](/docs/platform/events/overview) — the event hierarchy behind
  Karla triggers.
- [Shipment events](/docs/platform/events/shipments) — the full catalogue
  of shipment events and their payloads.
- [Claim events](/docs/platform/events/claims) — the claim events and their
  payloads.
- [Shopify](/docs/guides/shops/shopify) — installing the Karla Shopify app
  and the two notification paths.
- [Notify integrations](/docs/guides/notify/disable-carrier-emails) — using
  an external ESP (Klaviyo, Brevo, …) instead of Karla-sent emails.