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

# Email Templates Overview

> Reusable email templates the send_email voice-agent tool renders at call time (TLZ-470)

Email templates let you define reusable emails — a subject line and an HTML body with
placeholder tokens — that your voice agents send during calls via the existing `send_email`
tool. At send time the template is rendered server-side with live call context, so the raw
`{{token}}` syntax never appears in the delivered email.

Templates are strictly scoped to their owning organization. All endpoints require a valid
access token, and a request can only read or modify templates in organizations the token's
account owns.

## Template lifecycle

A template has a `status`:

* **draft** — editable, not available to agents.
* **active** — selectable in an agent's `send_email` tool; used at send time.
* **archived** — hidden from agent selection but preserved. Only archived templates can be
  deleted, and only when no agent references them.

## Placeholder tokens

Tokens use the `{{token}}` syntax and may declare a fallback with a pipe:
`{{caller_name|Valued Customer}}` resolves to the caller's name, or "Valued Customer" if it
is not available. Unknown tokens and tokens with no value and no fallback resolve to an empty
string — never the raw token text.

At send time, each token resolves in this priority order:

1. A value supplied in the tool call (agent-collected / custom tokens)
2. System call metadata (caller number, direction, agent name/id)
3. Organization / business configuration
4. Runtime date & time
5. The token's fallback text
6. Empty string

### Caller Context

These resolve automatically on every call:

| Token | Label | Description | Source |
| - | - | - | - |
| `{{caller_number}}` | Caller Phone Number | The caller's phone number, from the inbound ANI | ANI |
| `{{call_direction}}` | Call Direction | Whether the call was inbound or outbound | Inbound / Outbound |
| `{{agent_name}}` | Agent Name | The display name of the agent handling the call | Agent configuration |
| `{{agent_id}}` | Agent ID | The unique identifier of the agent | Agent configuration |
| `{{call_id}}` | Call ID | The SIP call identifier. Resolves on calls that arrive over SIP; empty on a web or playground session, which has none | SIP |
| `{{call_start_time}}` | Call Start Time | When this call began, as `MM/DD/YYYY h:MM AM/PM` (server local time) | Live call state |
| `{{call_duration}}` | Call Duration | Elapsed time **at the moment the email is sent** — the call is still in progress, so this is the duration so far, not the final figure. Rendered as `37s`, `4m 07s`, or `1h 02m` | Live call state |

These resolve only when the agent collects the value during the conversation — they are the
only two call-context tokens the language model is allowed to supply:

| Token | Label | Description | Source |
| - | - | - | - |
| `{{caller_name}}` | Caller Name | The caller's name, as stated on the call | Agent collected |
| `{{caller_email}}` | Caller Email | The caller's email address, collected during the conversation | Agent collected |

<Warning>
  **`{{called_number}}` is reserved and does not resolve yet.** It is accepted by the editor and
  validates normally, but at send time it renders as its fallback text, or as an empty string if
  none is given — the dialed DID is not yet plumbed into the call context. Do not build a
  template that depends on it.
</Warning>

### Business / Account

<Note>
  These resolve from the organization's **Template Variables**, set in the Dashboard under
  Customers → Manage → Template Variables. Email and SMS templates share them, so filling a
  field in once covers both — except `{{business_email}}`, which is email-only (it is the
  reply-to address, and a text message replies to the sending number instead). An organization
  that has not filled a field in leaves that token empty (or renders its fallback, if one is
  given), so `{{business_name|Acme Dental}}` is still worth writing for templates that may be
  used before the values are set.
</Note>

| Token | Label | Description | Source |
| - | - | - | - |
| `{{business_name}}` | Business Name | Your business name | Template Variables |
| `{{business_phone}}` | Business Phone | Your business phone number | Template Variables |
| `{{business_address}}` | Business Address | Your business address | Template Variables |
| `{{business_email}}` | Business Reply-To | The reply-to address for outbound email | Template Variables |
| `{{business_website}}` | Business Website | Your business website | Template Variables |

`{{business_email}}` does double duty: besides substituting wherever it is written, it becomes
the outbound email's **Reply-To** header. That header is read from the resolved value directly
rather than through the template, so a `{{business_email|...}}` fallback cannot supply it — the
organization must set the field for replies to reach them.

### Date / Time

| Token | Label | Description | Notes |
| - | - | - | - |
| `{{current_date}}` | Current Date | Today's date, resolved when the email is sent | Resolved at send (MM/DD/YYYY) |
| `{{current_time}}` | Current Time | The current time, resolved when the email is sent | Resolved at send (HH:MM AM/PM) |
| `{{current_datetime}}` | Current Date & Time | The current date and time, resolved when the email is sent | Resolved at send |
| `{{current_year}}` | Current Year | The current year, resolved when the email is sent | Resolved at send |

<Note>
  Authoritative call metadata (caller number, direction, dates, agent name/id) is resolved
  server-side and is never supplied by the language model, preventing fabricated values.
  Custom (agent-collected) tokens and `caller_name`/`caller_email` are the only model-supplied
  values.
</Note>

## Writing a template

The template editor has two modes, switched with the **Visual / HTML** toggle in the
toolbar. Your choice is remembered for next time.

* **Visual** — a rich-text editor: bold, italic, underline, strikethrough, bulleted and
  numbered lists, headings, links, horizontal rules, alignment, text and highlight colours.
  Placeholders appear as labelled chips rather than raw `{{token}}` text; an unrecognised
  token shows in orange.
* **HTML** — the raw source, with syntax highlighting and line numbers. HTML is stored
  exactly as written and is never stripped or sanitised.

<Note>
  **Visual mode is only available for templates built from the formatting the editor itself
  produces.** It is an allowlist, not a list of banned constructs: a template stays in HTML
  mode unless every tag, attribute and inline style in it survives a round trip through the
  rich-text editor unchanged.

  Allowed: `p`, `br`, `strong`, `b`, `em`, `i`, `u`, `s`, `strike`, `del`, `h1`–`h3`, `ul`,
  `ol`, `li`, `a`, `hr`, `blockquote`, `code`, `pre`, `span`, `mark` — with `href`, `target`,
  `rel`, `data-color`, and the `text-align`, `color` and `background-color` styles.

  Anything else disables Visual mode, including `<table>`, `<div>`, `<img>`, `<style>`,
  Outlook conditional comments, `class=`, and inline styles such as `padding`, `margin` or
  `width`. A placeholder inside an attribute (for example `href="{{business_website}}"`)
  does too.

  The reason is that a rich-text editor cannot represent those constructs, so opening such a
  template visually and saving would silently discard the layout. The Visual button is
  disabled instead, with the specific reason shown beneath the toggle, and the stored HTML is
  sent exactly as written.
</Note>

## Sample data and preview

Each template can carry sample values used only for the preview and for test sends — never
when a real email is sent. Any token left blank falls back to an account-wide default, so
common values (a standard test caller name and number) need only be set once. Account
defaults are configured from the dashboard.

Unresolved tokens are highlighted in the preview rather than vanishing, so their position
in the layout stays visible.

## Custom parameters

Define custom, organization-scoped tokens (e.g. `{{account_number}}`) for data your agent
collects during a call. Token names must be lowercase letters, numbers, and underscores. In
an agent's `send_email` tool configuration you map each custom token to the agent context key
it is collected under.

Each custom parameter also carries an optional **description** and a **data type** — one of
`text`, `number`, `date`, `phone`, `email`, or `currency`. The type is descriptive: it tells
the template author what the agent should collect. Every token renders as a string at send
time regardless of type.

## Agent tool integration

Select an **active** template on an agent's `send_email` tool. When configured, the tool
renders the template's subject and body from the call context; when no template is configured
the tool behaves exactly as before (free-form `subject` and `body`), so existing agents are
unaffected.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.