# Templates y Variables

ReallyQuickEmails utiliza un motor de templates basado en **Handlebars** con extensiones propias. Puedes crear correos dinamicos con variables, condicionales, loops y helpers de formateo que se resuelven al momento del envio.

***

## Conceptos basicos

### Variables

Usa `{{nombreVariable}}` o `{nombreVariable}` para insertar valores dinamicos en tu template. Ambas sintaxis son equivalentes.

**En el template:**

```html
<h1>Hola, {{nombre}}!</h1>
<p>Tu cuenta en {empresa} ha sido creada exitosamente.</p>
```

**En el request body (API publica v1):**

```json
{
  "template_id": "550e8400-e29b-41d4-a716-446655440000",
  "variables": {
    "nombre": "Carlos",
    "empresa": "TechStore"
  }
}
```

**Resultado renderizado:**

```html
<h1>Hola, Carlos!</h1>
<p>Tu cuenta en TechStore ha sido creada exitosamente.</p>
```

> **Nota:** Tambien puedes usar la sintaxis `{variable || "valor por defecto"}` para proporcionar un fallback cuando la variable no existe.

***

### Condicionales

Usa `{{#if variable}}...{{/if}}` para mostrar contenido solo cuando una variable existe y es truthy. Combina con `{{else}}` para manejar el caso contrario.

**En el template:**

```html
{{#if premium}}
  <p>Gracias por ser miembro Premium. Tienes envio gratuito en todos tus pedidos.</p>
{{else}}
  <p>Actualiza a Premium para obtener envio gratuito.</p>
{{/if}}
```

**En el request body:**

```json
{
  "data": {
    "premium": true
  }
}
```

> **Nota:** Handlebars evalua como falsy los valores `false`, `undefined`, `null`, `""`, `0` y arrays vacios `[]`.

***

### Loops

Usa `{{#each arreglo}}...{{/each}}` para iterar sobre una lista de elementos. Dentro del loop, `{{this}}` referencia al elemento actual y puedes acceder a sus propiedades directamente.

**En el template:**

```html
<table>
  <tr>
    <th>Producto</th>
    <th>Cantidad</th>
    <th>Precio</th>
  </tr>
  {{#each productos}}
  <tr>
    <td>{{this.nombre}}</td>
    <td>{{this.cantidad}}</td>
    <td>{{formatCurrency this.precio}}</td>
  </tr>
  {{/each}}
</table>
```

**En el request body:**

```json
{
  "data": {
    "productos": [
      { "nombre": "Camiseta Azul", "cantidad": 2, "precio": 15990 },
      { "nombre": "Pantalon Negro", "cantidad": 1, "precio": 29990 },
      { "nombre": "Zapatillas Blancas", "cantidad": 1, "precio": 45990 }
    ]
  }
}
```

**Variables especiales dentro de loops:**

| Variable     | Descripcion                                 |
| ------------ | ------------------------------------------- |
| `{{this}}`   | El elemento actual de la iteracion          |
| `{{@index}}` | Indice del elemento (comienza en 0)         |
| `{{@first}}` | `true` si es el primer elemento             |
| `{{@last}}`  | `true` si es el ultimo elemento             |
| `{{@key}}`   | La clave actual (cuando se itera un objeto) |

***

## Helpers integrados

ReallyQuickEmails incluye helpers de Handlebars adicionales para formateo comun en correos transaccionales.

### `formatCurrency`

Formatea un numero como moneda usando el formato `en-US`. Por defecto usa USD como moneda. Acepta un segundo parametro opcional para especificar la moneda.

```html
<p>Total: {{formatCurrency total}}</p>
```

Con `"total": 61970` produce: `$61,970.00`

Para usar otra moneda:

```html
<p>Total: {{formatCurrency total "CLP"}}</p>
```

### `multiply`

Multiplica dos valores numericos. El resultado se redondea a 2 decimales.

```html
<p>Subtotal: {{formatCurrency (multiply cantidad precio)}}</p>
```

### `formatDate`

Formatea una fecha ISO 8601 a un formato legible en espanol. Acepta un segundo parametro opcional para el formato.

**Formato por defecto (`short`):**

```html
<p>Fecha: {{formatDate fechaEntrega}}</p>
```

Con `"fechaEntrega": "2025-03-15T00:00:00Z"` produce: `15/3/2025`

**Formato largo (`long`):**

```html
<p>Fecha: {{formatDate fechaEntrega "long"}}</p>
```

Con `"fechaEntrega": "2025-03-15T00:00:00Z"` produce: `viernes, 15 de marzo de 2025`

### `default`

Proporciona un valor por defecto cuando la variable es `undefined` o `null`.

```html
<p>Hola, {{default nombre "Cliente"}}!</p>
```

Si `nombre` no esta definido en `data`, se renderiza como `Hola, Cliente!`.

### `json`

Serializa un objeto a formato JSON con indentacion. Util para depuracion o para incluir datos estructurados en el correo.

```html
<pre>{{json datos}}</pre>
```

Con `"datos": {"clave": "valor"}` produce:

```json
{
  "clave": "valor"
}
```

***

## Identificar un template

Puedes referenciar un template de dos formas en la API publica (`/v1/send-template-email`):

| Campo                  | Tipo          | Descripcion                                 |
| ---------------------- | ------------- | ------------------------------------------- |
| `template_id`          | string (UUID) | UUID unico del template                     |
| `template_internal_id` | number        | ID interno auto-incrementado (por proyecto) |

```json
{
  "template_id": "550e8400-e29b-41d4-a716-446655440000",
  "recipient_email": "usuario@ejemplo.com",
  "sender_email": "tienda@tudominio.com",
  "variables": {
    "nombre": "Ana",
    "numeroPedido": "5021"
  }
}
```

* Si el template no existe en el proyecto, la API retorna un error `404`.
* El template debe pertenecer al mismo proyecto asociado a la Secret Key utilizada.

***

## El objeto `variables`

El objeto `variables` es un JSON plano (o anidado) donde cada clave corresponde a una variable del template.

### Ejemplo completo

**Request:**

```bash
curl -X POST https://api.reallyquickemails.com/v1/send-template-email \
  -H "Authorization: Bearer sk_proj_tu_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "550e8400-e29b-41d4-a716-446655440000",
    "recipient_email": "juan.perez@ejemplo.com",
    "sender_email": "pedidos@mitienda.com",
    "variables": {
      "nombre": "Juan",
      "numeroPedido": "3847",
      "fechaCompra": "2026-02-20T14:30:00Z",
      "premium": true,
      "direccion": {
        "calle": "Av. Providencia 1234",
        "ciudad": "Santiago",
        "region": "Metropolitana"
      },
      "productos": [
        { "nombre": "Audifonos Bluetooth", "cantidad": 1, "precio": 34990 },
        { "nombre": "Cable USB-C", "cantidad": 3, "precio": 5990 }
      ],
      "subtotal": 52960,
      "descuento": 5000,
      "total": 47960
    }
  }'
```

**Template Handlebars correspondiente:**

```html
<h1>Gracias por tu compra, {{nombre}}!</h1>
<p>Pedido #{{numeroPedido}} - {{formatDate fechaCompra}}</p>

{{#if premium}}
<p>Como miembro Premium, tu envio es gratuito.</p>
{{/if}}

<table>
  {{#each productos}}
  <tr>
    <td>{{this.nombre}}</td>
    <td>x{{this.cantidad}}</td>
    <td>{{formatCurrency this.precio}}</td>
    <td>{{formatCurrency (multiply this.cantidad this.precio)}}</td>
  </tr>
  {{/each}}
</table>

<p>Subtotal: {{formatCurrency subtotal}}</p>
<p>Descuento: -{{formatCurrency descuento}}</p>
<p><strong>Total: {{formatCurrency total}}</strong></p>

<p>Direccion de envio: {{direccion.calle}}, {{direccion.ciudad}}, {{direccion.region}}</p>
```

***

## Acceso a propiedades anidadas

Usa notacion de punto para acceder a objetos anidados dentro de `data`:

```html
<p>Ciudad: {{direccion.ciudad}}</p>
<p>Region: {{direccion.region}}</p>
```

***

## Buenas practicas

* **Usa `default` para variables opcionales** para evitar que aparezcan espacios vacios en el correo.
* **Valida tu objeto `data`** antes de enviar. Si un template espera variables que no existen en `data`, se renderizaran como cadenas vacias sin error.
* **Nombra tus `templateId` de forma descriptiva** usando kebab-case: `bienvenida`, `confirmacion-envio`, `recuperar-carro`, `factura-mensual`.
* **Prueba tus templates** en el editor de ReallyQuickEmails con datos de ejemplo antes de integrar con la API.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://reallyquickemails.gitbook.io/reallyquickemails-docs/guias/templates.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.