API de Plantillas de Correo Electrónico

La API de Plantillas de Correo permite a los administradores personalizar los correos transaccionales enviados por Auris. Cada uno de los trece tipos de plantilla corresponde a un evento específico (verificación, restablecimiento de contraseña, magic link, alertas de seguridad, …) y puede personalizarse con HTML y variables dinámicas, de forma independiente por idioma.

Auris incluye plantillas predeterminadas para todos los tipos en cinco idiomas (en, it, fr, de, es). Cuando existe una plantilla personalizada para un tipo y un idioma, se usa para todos los correos futuros de ese tipo; en caso contrario se usa la predeterminada con la marca del tenant. Orden de resolución en el envío: personalizada (idioma solicitado) -> personalizada (en) -> predeterminada (idioma solicitado) -> predeterminada (en).

Todos los endpoints requieren un token Bearer con el permiso manage:security y seleccionan el tenant mediante la cabecera x-tenant (el identificador de realm del tenant).

Listar Plantillas

Respuesta de éxito (200)

{
  "templates": [
    {
      "type": "verification",
      "label": "Email Verification",
      "description": "Sent when a new user registers to verify their email address.",
      "variables": ["email", "link", "expiresIn", "year", "month", "day", "date"],
      "hasCustomTemplate": true,
      "active": true,
      "updatedAt": "2026-07-20T10:00:00.000Z",
      "customLocales": ["en", "es"]
    }
  ],
  "availableLocales": ["en", "it", "fr", "de", "es"],
  "wellKnownLocales": { "en": "English", "es": "Español", "pt-BR": "Português (Brasil)" }
}

Obtener una Plantilla

Respuesta de éxito (200)

{
  "type": "verification",
  "locale": "es",
  "label": "Email Verification",
  "description": "Sent when a new user registers to verify their email address.",
  "variables": ["email", "link", "expiresIn", "year", "month", "day", "date"],
  "hasCustomTemplate": false,
  "subject": null,
  "htmlBody": null,
  "metadata": null,
  "active": true,
  "updatedAt": null,
  "defaultSubject": "Verifica tu dirección de correo",
  "defaultHtmlBody": "<!DOCTYPE html>...",
  "availableLocales": ["en", "it", "fr", "de", "es"],
  "customLocales": ["en"],
  "hasDefaultTemplate": true,
  "wellKnownLocales": { "en": "English", "es": "Español" }
}

subject, htmlBody y metadata son null cuando no existe plantilla personalizada para el idioma solicitado. defaultSubject y defaultHtmlBody contienen siempre la plantilla integrada, renderizada con la marca del tenant (logo, color, pie white-label) exactamente igual que en un envío real. hasDefaultTemplate indica si el idioma solicitado tiene una predeterminada integrada (en, it, fr, de, es); los demás idiomas recurren al inglés.

Respuestas de error

Actualizar una Plantilla

Body de la petición

{
  "subject": "Verifica tu correo — {{email}}",
  "htmlBody": "<!DOCTYPE html><html><body><h1>Verifica tu correo</h1><p>Hola {{email}},</p><p><a href=\"{{link}}\">Confirma tu dirección</a></p><p>El enlace caduca en {{expiresIn}}.</p></body></html>",
  "locale": "es",
  "metadata": { "source": "code" }
}

El cuerpo HTML se sanea en el servidor antes de guardarse: se eliminan las etiquetas <script>, los atributos de manejadores de eventos (onclick, …), los URI javascript:/data:, las etiquetas <iframe>/<embed>/<object>/<form>/<base> y las construcciones CSS peligrosas.

Respuesta de éxito (200) — el registro de la plantilla guardada:

{
  "id": "cltpl123",
  "tenantId": "tnt_ScUtrVKUKGxtu7WY",
  "type": "verification",
  "locale": "es",
  "subject": "Verifica tu correo — {{email}}",
  "htmlBody": "<!DOCTYPE html>...",
  "metadata": { "source": "code" },
  "active": true,
  "createdAt": "2026-07-23T09:00:00.000Z",
  "updatedAt": "2026-07-23T09:00:00.000Z"
}

Respuestas de error

Eliminar una Plantilla

Respuesta de éxito (200)

{ "success": true }

Previsualizar una Plantilla

Body de la petición

{
  "subject": "Verifica tu correo — {{email}}",
  "htmlBody": "<!DOCTYPE html>..."
}

Respuesta de éxito (200)

{
  "subject": "Verifica tu correo — [email protected]",
  "html": "<!DOCTYPE html>...",
  "variables": {
    "email": "[email protected]",
    "link": "https://console.auris.dev/verify-email?token=abc123",
    "expiresIn": "24 hours",
    "year": "2026",
    "month": "07",
    "day": "23",
    "date": "2026-07-23"
  }
}

El campo variables devuelve los valores de ejemplo sustituidos. El cuerpo HTML se sanea antes del renderizado; el asunto se renderiza como texto plano (sin escape HTML de los valores).

Correo de Prueba

Body de la petición

{
  "subject": "Verifica tu correo — {{email}}",
  "htmlBody": "<!DOCTYPE html>...",
  "recipientEmail": "[email protected]"
}

Respuesta de éxito (200)

{ "success": true, "sentTo": "[email protected]" }

Respuestas de error

Tipos de Plantilla

Auris soporta trece tipos de plantilla de correo transaccional:

Las variables de fecha globales year, month, day y date (formato YYYY-MM-DD) se inyectan automáticamente en cada renderizado, además de las variables por tipo listadas arriba.

Sintaxis de las Plantillas

• {{variable}} — se sustituye por el valor. En el cuerpo HTML los valores llevan escape HTML automático para prevenir inyección; en el asunto se insertan como texto plano.
• {{{variable}}} — interpolación raw sin escape. Solo para fragmentos HTML de confianza construidos en el servidor.
• {{#if variable}}...{{/if}} — el bloque se conserva solo cuando la variable tiene un valor no vacío; en caso contrario se elimina por completo (markup incluido). Ejemplo: la plantilla predeterminada de magic_link muestra el botón secundario de aprobación solo cuando approveLink tiene valor.

Los placeholders desconocidos permanecen tal cual en la salida. La notación con punto y los bucles no están soportados.

<h1>Inicia sesión en {{tenantName}}</h1>
<p><a href="{{link}}">Iniciar sesión en este dispositivo</a></p>
{{#if approveLink}}
<p><a href="{{approveLink}}">Aprobar en el dispositivo de origen</a></p>
{{/if}}
<p>El enlace caduca en {{expiresIn}}.</p>

Referencia de Permisos

Relacionado

• Personalizar Plantillas de Correo — Guía paso a paso de personalización
• Plantillas de Correo — Editar plantillas visualmente desde la Consola