# Templates (/concepts/templates)

A template lives in the Bitelio dashboard and can power any kind of send: campaigns, workflow steps, or transactional emails dispatched through `/v1/send`.

## Anatomy of a template

Content, sender identity, and sending behaviour are all packaged together in the template:

import {TypeTable} from 'fumadocs-ui/components/type-table';

<TypeTable
  type={{
  name: { type: 'string', required: true, description: 'Internal label displayed in the dashboard.' },
  description: { type: 'string', description: 'Free-form internal note; optional.' },
  subject: { type: 'string', required: true, description: 'Subject line; template variables are supported.' },
  body: { type: 'string', required: true, description: 'The HTML body, with template variable support.' },
  from: { type: 'string', required: true, description: 'Sending address — its domain must be verified.' },
  fromName: { type: 'string', description: 'Display name shown as the sender; optional.' },
  replyTo: { type: 'string', description: 'Reply-to address; optional.' },
  type: { type: 'string', required: true, description: 'One of `MARKETING`, `TRANSACTIONAL`, or `HEADLESS`. See [Template types](#templates-types).' },
  style: { type: 'object', description: "Metadata for the dashboard's drag-and-drop editor. Safe to leave out when working with templates over the API." },
}}
/>

When `/v1/send` references a template, any of `subject`, `body`, `from`, `fromName`, and `replyTo` can be overridden per request — the values stored on the template serve only as defaults.

### Sender domain verification

A template's `from` address has to belong to a verified domain; a create or update using an unverified one is rejected with `403`. See [Verifying domains](/guides/verifying-domains).

## Designing templates

You can build templates in the built-in editor or paste in HTML you've authored elsewhere.

### Personalization

Templates are personalized with handlebars-style placeholders — write `{{ key }}` and it resolves to the contact's data value for that key.

#### Always Available Variables

Whatever custom data a contact has, these variables can always be used:

| Variable             | Description                            |
| -------------------- | -------------------------------------- |
| `{{id}}`             | The contact's unique identifier        |
| `{{email}}`          | The contact's email address            |
| `{{unsubscribeUrl}}` | URL to the unsubscribe page            |
| `{{subscribeUrl}}`   | URL to the subscribe/resubscribe page  |
| `{{manageUrl}}`      | URL to the preferences management page |

#### Fallback Values

A variable that may be missing can carry a fallback:

```
Hello {{firstName ?? 'there'}}!
```

When `firstName` is absent, the output becomes "Hello there!"

#### Special Fields

These fields are managed by Bitelio, yet remain usable in templates.

| Variable         | Description                                         |
| ---------------- | --------------------------------------------------- |
| `{{subscribed}}` | Contact's subscription status (true/false)          |
| `{{locale}}`     | Contact's preferred locale (e.g., 'en', 'fr', 'es') |

### Previewing templates

Pick a contact in the preview window to render the template with that contact's real data filled in — a quick way to check exactly what an individual recipient would see.

## Duplicating and finding usage

* `POST /templates/:id/duplicate` — makes an editable copy, handy for A/B variants or as a base for a related email.
* `GET /templates/:id/usage` — returns every campaign, workflow step, and other reference pointing at the template. Run it before editing ("what depends on this?") or before deleting ("any stragglers left?").

## Templates types

Bitelio has three template types. All three are sent with equal priority — deliverability and performance are not reasons to choose one over another.

| Type          | Respects opt-out | Bitelio unsubscribe footer | Description                                                                                                                                                                                                          |
| ------------- | :--------------: | :------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Marketing     |        Yes       |             Yes            | A Bitelio-hosted unsubscribe footer is appended automatically, and unsubscribed contacts never receive it                                                                                                            |
| Transactional |        No        |             No             | Carries no unsubscribe option and reaches every contact, whatever their subscription state                                                                                                                           |
| Headless      |        Yes       |             No             | Honours opt-out exactly like marketing, but Bitelio appends no footer — supplying an unsubscribe path in the body is on you. Link to Bitelio's managed unsubscribe page with `{{unsubscribeUrl}}` or `{{manageUrl}}` |

## What's next

<Cards>
  <Card title="Transactional emails" href="/concepts/transactional-emails">
    Dispatch templated emails straight from `/v1/send`.
  </Card>

  <Card title="Campaigns" href="/concepts/campaigns">
    Send a template to a segment or broader audience.
  </Card>

  <Card title="Workflows" href="/concepts/workflows">
    Use templates inside automated journeys.
  </Card>

  <Card title="Localization" href="/guides/localization">
    Localize the unsubscribe footer and contact-facing pages.
  </Card>
</Cards>