> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiveku.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Templates

> Create reusable email templates with variables

Templates let you define email HTML once, store it in Hiveku, and render it with dynamic variables at send time. They are the right tool for any email you send more than a handful of times — welcome emails, password resets, order confirmations, subscription renewals.

## Why templates

* **Reuse** — One source of truth; update HTML in one place
* **Consistency** — Every send uses the same layout, tokens, and defaults
* **Versioning** — Every edit creates a new version; roll back if something breaks
* **Separation of concerns** — Designers own the HTML, engineers just pass variables
* **Analytics** — Track open and click rates per template

## Create a template

<Steps>
  <Step title="Open Templates">
    Go to **Settings > Email > Templates > New**.
  </Step>

  <Step title="Write the HTML">
    Use the built-in editor or paste in HTML from your design tool (MJML, Maizzle, Unlayer, etc.). The editor renders a live preview.
  </Step>

  <Step title="Declare variables">
    Add each variable the template uses, with a name, type, and whether it is required. See [Variables](#variables) below.
  </Step>

  <Step title="Set defaults">
    Optionally set a default `from` address and `reply_to` for this template.
  </Step>

  <Step title="Save">
    Saving creates version 1. Subsequent edits create new versions.
  </Step>
</Steps>

## Variables

Variables use `{{double-brace}}` syntax and support dot notation for nested values:

```html theme={null}
<h1>Hi {{customer_name}},</h1>
<p>Your order #{{order.number}} for ${{order.total}} has shipped.</p>
<p>Track it here: {{tracking_url}}</p>
```

Declare each variable with a type hint:

| Type      | Example        | Notes                                    |
| --------- | -------------- | ---------------------------------------- |
| `string`  | `"Alice"`      | Default; supports HTML-escaped rendering |
| `number`  | `42`           | Formatted per locale                     |
| `boolean` | `true`         | Useful for conditionals                  |
| `date`    | `"2026-04-17"` | Formatted to the recipient's locale      |

Hiveku validates the `variables` payload on every send — passing a missing required variable fails with `422 Unprocessable Entity` before the email is ever queued.

## Template-specific defaults

Set these per template so callers do not have to pass them every time:

* **Default `from`** — e.g., `"Acme Orders <orders@mail.acme.com>"`
* **Default `reply_to`** — e.g., `"support@acme.com"`
* **Default subject** — Can still be overridden at send time

## Version control

Every save creates a new version. You can:

* View a diff between any two versions
* Preview any version with sample variables
* Roll back to a previous version with one click
* Send from a specific version (pin legacy flows to an older version if needed)

<Tip>
  When making breaking changes (renaming variables, removing fields), create a new template instead of a new version. This gives you a clean cutover without surprising in-flight callers.
</Tip>

## Send with a template

```ts theme={null}
import { Hiveku } from "@hiveku-apps/email";

const hiveku = new Hiveku({ apiKey: process.env.HIVEKU_API_KEY! });

await hiveku.emails.sendTemplate({
  template_id: "tmpl_order_shipped",
  to: "customer@example.com",
  variables: {
    customer_name: "Sam",
    order: {
      number: "1024",
      total: 49.99,
    },
    tracking_url: "https://acme.com/track/ABC123",
  },
});
```

You can still override any top-level email parameter (`subject`, `from`, `tags`, etc.) at send time — the template's defaults fill in anything you omit. See [Sending Emails](/email/sending) for the full parameter list.

## Tracking template usage

Each template has a stats view showing:

* Total sends (today, 7 days, 30 days)
* Delivery rate
* Open and click rates
* Bounce and complaint counts
* Version breakdown (which version delivered which sends)

Use this to A/B test subject lines, spot regressions after a template edit, and identify high-complaint templates that need copy review.