API Template Email

L’API Template Email consente agli amministratori di personalizzare le email transazionali inviate da Auris. Ognuno dei tredici tipi di template corrisponde a un evento specifico (verifica, reset password, magic link, avvisi di sicurezza, …) e può essere personalizzato con HTML e variabili dinamiche, in modo indipendente per ogni lingua.

Auris include template predefiniti per tutti i tipi in cinque lingue (en, it, fr, de, es). Quando esiste un template personalizzato per un tipo e una lingua, viene usato per tutte le email future di quel tipo; altrimenti viene usato il default con il branding del tenant. Ordine di risoluzione all’invio: personalizzato (lingua richiesta) -> personalizzato (en) -> default (lingua richiesta) -> default (en).

Tutti gli endpoint richiedono un token Bearer con il permesso manage:security e selezionano il tenant tramite l’header x-tenant (l’identificatore del realm del tenant).

Elenca i Template

Risposta di successo (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", "it"]
    }
  ],
  "availableLocales": ["en", "it", "fr", "de", "es"],
  "wellKnownLocales": { "en": "English", "it": "Italiano", "pt-BR": "Português (Brasil)" }
}

Ottieni un Template

Risposta di successo (200)

{
  "type": "verification",
  "locale": "it",
  "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 il tuo indirizzo email",
  "defaultHtmlBody": "<!DOCTYPE html>...",
  "availableLocales": ["en", "it", "fr", "de", "es"],
  "customLocales": ["en"],
  "hasDefaultTemplate": true,
  "wellKnownLocales": { "en": "English", "it": "Italiano" }
}

subject, htmlBody e metadata sono null quando non esiste un template personalizzato per la lingua richiesta. defaultSubject e defaultHtmlBody contengono sempre il template integrato, renderizzato con il branding del tenant (logo, colore, footer white-label) esattamente come per un invio reale. hasDefaultTemplate indica se la lingua richiesta ha un default integrato (en, it, fr, de, es); le altre lingue ricadono sull’inglese.

Risposte di errore

Aggiorna un Template

Body della richiesta

{
  "subject": "Verifica la tua email — {{email}}",
  "htmlBody": "<!DOCTYPE html><html><body><h1>Verifica la tua email</h1><p>Ciao {{email}},</p><p><a href=\"{{link}}\">Conferma il tuo indirizzo</a></p><p>Il link scade tra {{expiresIn}}.</p></body></html>",
  "locale": "it",
  "metadata": { "source": "code" }
}

Il corpo HTML viene sanificato lato server prima del salvataggio: tag <script>, attributi di gestione eventi (onclick, …), URI javascript:/data:, tag <iframe>/<embed>/<object>/<form>/<base> e costrutti CSS pericolosi vengono rimossi.

Risposta di successo (200) — il record del template salvato:

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

Risposte di errore

Elimina un Template

Risposta di successo (200)

{ "success": true }

Anteprima di un Template

Body della richiesta

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

Risposta di successo (200)

{
  "subject": "Verifica la tua email — [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"
  }
}

Il campo variables riporta i valori di esempio sostituiti. Il corpo HTML viene sanificato prima del render; l’oggetto viene renderizzato come testo semplice (senza escape HTML dei valori).

Email di Test

Body della richiesta

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

Risposta di successo (200)

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

Risposte di errore

Tipi di Template

Auris supporta tredici tipi di template email transazionali:

Le variabili di data globali year, month, day e date (formato YYYY-MM-DD) vengono iniettate automaticamente in ogni render, in aggiunta alle variabili per tipo elencate sopra.

Sintassi dei Template

• {{variabile}} — sostituita con il valore. Nel corpo HTML i valori subiscono escape HTML automatico per prevenire injection; nell’oggetto vengono inseriti come testo semplice.
• {{{variabile}}} — interpolazione raw senza escape. Solo per frammenti HTML fidati costruiti lato server.
• {{#if variabile}}...{{/if}} — il blocco viene mantenuto solo quando la variabile ha un valore non vuoto; altrimenti viene rimosso interamente (markup incluso). Esempio: il template predefinito di magic_link mostra il pulsante di approvazione secondario solo quando approveLink è valorizzato.

I placeholder sconosciuti restano invariati nell’output. Dot notation e cicli non sono supportati.

<h1>Accedi a {{tenantName}}</h1>
<p><a href="{{link}}">Accedi su questo dispositivo</a></p>
{{#if approveLink}}
<p><a href="{{approveLink}}">Approva sul dispositivo di origine</a></p>
{{/if}}
<p>Il link scade tra {{expiresIn}}.</p>

Riferimento Permessi

Correlati

• Personalizzare i Template Email — Guida passo passo alla personalizzazione
• Template Email — Modifica i template visivamente dalla Console