Parámetros y tipos

Cada plantilla tiene un esquema de parámetros. Documenta lo que espera la plantilla, alimenta el panel de parámetros del editor, genera tipos de TypeScript y, sobre todo, valida cada envío. Una solicitud cuyos parámetros no encajan falla con 422 invalid_template_params antes de consumir ningún crédito.

Definir parámetros

Cada parámetro tiene:

Campo	Significado
name	Identificador que se usa en la plantilla, p. ej. customer_name. Letras, dígitos, _ y -; se admiten nombres con puntos como customer.name, que generan objetos anidados. frontmail, this y root están reservados.
label, description	Se muestran en el panel de parámetros y en los fragmentos de código generados.
type	Uno de los tipos de abajo.
required	Valor que falta (o vacío) → error.
default	Se usa cuando falta el valor. Un parámetro con valor predeterminado nunca falla por required.
sampleValue	Lo usan la vista previa y los envíos de prueba.
Reglas	minLength / maxLength, min / max, pattern (regex), enumValues, itemFields, según el tipo.

En el editor, abre Parámetros y añade parámetros con Añadir parámetro, o haz clic en Detectar en la plantilla: Frontmail analiza el HTML, el asunto y los campos de destinatario en busca de {{marcadores}} y propone un parámetro para cada uno, incluidos los campos de elemento usados dentro de bloques {{#each}}.

Tipos

Tipo	Acepta (JSON)	Conversión desde cadenas (formularios)	Reglas	Resultado en la plantilla
string	cadena, número, booleano	se convierte en cadena	minLength, maxLength, pattern	texto escapado
text	igual que string	igual	igual	texto escapado; usa {{nl2br x}} para conservar los saltos de línea
email	cadena	se recortan los espacios	debe ser una dirección válida (máx. 254 caracteres); maxLength, pattern	texto escapado
url	cadena	se recortan los espacios	solo http, https, mailto o tel	texto escapado
number	número	"1234.5", "1 234,5" (se aceptan espacios y la coma decimal)	min, max	número (usa formatNumber / formatMoney)
boolean	booleano, 1, 0	true/false, on/off, 1/0, yes/no, y/n, ano/ne (sin distinguir mayúsculas)	–	true / false para {{#if}}
date	cadena ISO, milisegundos epoch	YYYY-MM-DD (se mantiene como fecha de calendario) o YYYY-MM-DDTHH:mm… (se normaliza a ISO UTC)	–	cadena (usa formatDate)
enum	cadena o número	se recortan los espacios	el valor debe estar en enumValues	texto escapado
html	cadena	–	minLength, maxLength	HTML saneado, renderizado como marcado
list	array de objetos	se analiza una cadena JSON	min, max elementos (máximo predeterminado 500); cada elemento se valida con itemFields	array para {{#each}}

Otras reglas:

• Una cadena vacía o null cuenta como que falta, así que se aplican required y default.
• Los parámetros de cadena sin maxLength están limitados a 50 000 caracteres.
• Todos los parámetros juntos pueden ocupar como máximo 256 kB de JSON; los payloads más grandes fallan con payload_too_large.
• pattern debe coincidir con el valor completo (se ancla automáticamente), p. ej. [A-Z]{2}\d{4}.

Conversión de los datos de formularios

sendForm() y POST /v1/send-form envían multipart/form-data, donde todos los valores son cadenas. Frontmail los convierte según los tipos declarados, así que la misma plantilla funciona con JSON y con formularios:

<input name="guests" value="3">            <!-- number → 3 -->
<input name="price" value="1 299,50">      <!-- number → 1299.5 -->
<input type="checkbox" name="newsletter">  <!-- marcada "on" → true; sin marcar → falta → default -->
<input type="date" name="arrival">         <!-- "2026-10-01" se queda "2026-10-01" -->
<input type="hidden" name="items" value='[{"title":"Habitación","qty":1}]'> <!-- list → JSON analizado -->

Los campos de archivo se convierten en archivos adjuntos, no en parámetros.

Parámetros desconocidos y modo estricto

Por defecto, los parámetros que no están en el esquema se pasan a la plantilla (así puedes empezar a enviar antes de terminar el esquema). Activa Parámetros estrictos en Seguridad → Protección contra abusos para rechazarlos con un problema unknown_param; es lo recomendado para las plantillas que se usan con la clave pública.

La respuesta de error

{
  "error": {
    "code": "invalid_template_params",
    "message": "Invalid template parameters. email: Invalid email address. message: Must be at least 10 characters.",
    "docs_url": "https://docs.frontmail.dev/reference/errors/#invalid-template-params",
    "details": {
      "issues": [
        { "param": "email", "code": "invalid_email", "message": "Invalid email address." },
        { "param": "message", "code": "too_short", "message": "Must be at least 10 characters.", "meta": { "min": 10 } },
        { "param": "items[2].qty", "code": "too_small", "message": "Must be at least 1.", "meta": { "min": 1 } }
      ]
    }
  }
}

Códigos de problema: required, invalid_type, too_short, too_long, too_small, too_big, invalid_format, invalid_email, invalid_url, invalid_enum, invalid_date, unknown_param, payload_too_large. Usa param para mostrar el mensaje junto al campo correcto del formulario; meta contiene el límite para que puedas traducir el mensaje tú mismo.

Escapado y el tipo html

Todos los valores se escapan como HTML al renderizarse, incluso dentro de {{{triples llaves}}}, que Frontmail trata igual que {{llaves dobles}}. Así nadie puede inyectar marcado en tu correo a través de una clave pública. Si necesitas texto enriquecido, declara el parámetro como html: pasa por un saneador estricto (solo etiquetas de formato, enlaces, tablas e imágenes; sin scripts, formularios, iframes ni manejadores de eventos; solo estilos en línea seguros). Más detalles en la guía de Handlebars.

En el panel

Consulta Editor de plantillas para los paneles Parámetros y Datos de ejemplo.