Personalizzare i Template Email

Auris invia email transazionali nei momenti critici del ciclo di vita utente: verifica email, reset password, login con magic link, inviti, avvisi di sicurezza e altro. Di default queste email usano un template pulito renderizzato con il branding del tuo tenant (nome azienda, logo, colore primario). Personalizzarle ti dà pieno controllo sull’HTML, così ogni punto di contatto — dalla prima email di verifica a un avviso di accesso sospetto mesi dopo — è coerente con il tuo prodotto.

Questa guida ti accompagna nella modifica dei template dalla Console, nell’uso di variabili dinamiche e blocchi condizionali, nell’anteprima e nel test delle modifiche, nella gestione delle lingue e nella gestione programmatica via API.

Tipi di Template

Auris include tredici tipi di template email. Ognuno viene attivato automaticamente al momento giusto.

Ogni template si personalizza in modo indipendente, e in modo indipendente per lingua.

Passo 1: Apri l’Editor di Template

1. Apri la Console Auris e vai su Impostazioni, poi Template Email
2. Vedrai tutti i tredici tipi di template con il loro stato attuale (default o personalizzato)
3. Clicca sul tipo di template che vuoi modificare

Passo 2: Scegli una Modalità di Modifica

L’editor offre tre modalità:

• Editor tema — personalizza identità (logo, nome brand, testo footer), colori, tipografia, pulsanti, layout e contenuto del corpo tramite pannelli visuali.
• Builder visuale — componi l’email a blocchi su un canvas.
• Editor codice — modifica HTML e CSS grezzi. Una libreria di snippet offre punti di partenza pronti.

Qualunque modalità usi, il risultato è un documento HTML completo salvato per tipo di template e lingua. La maggior parte dei client email ha un supporto CSS limitato, quindi stili inline e layout a tabelle sono l’approccio più affidabile.

Passo 3: Usa le Variabili dei Template

Le variabili usano la sintassi {{nomeVariabile}}. Quando Auris invia l’email, ogni placeholder viene sostituito con il valore reale per quell’utente e quell’evento. Nel corpo i valori subiscono escape HTML automatico; nell’oggetto vengono inseriti come testo semplice.

Variabili Globali (disponibili in tutti i template)

Variabili per Tipo

Condizionali e Interpolazione Raw

• {{#if variabile}}...{{/if}} mantiene il contenuto racchiuso solo quando la variabile ha un valore non vuoto. Altrimenti il blocco — markup incluso — viene rimosso.
• {{{variabile}}} inserisce il valore raw senza escape HTML. Usala solo per frammenti HTML fidati costruiti lato server.

Esempio per un template magic_link:

<h1>Accedi a {{tenantName}}</h1>
<p><a href="{{link}}">Accedi su questo dispositivo</a></p>
{{#if approveLink}}
<p><a href="{{approveLink}}">Approva sul dispositivo da cui hai iniziato l'accesso</a></p>
{{/if}}
<p>Questo link scade tra {{expiresIn}}.</p>

Passo 4: Gestisci le Lingue

I template predefiniti integrati esistono in cinque lingue: inglese (en), italiano (it), francese (fr), tedesco (de) e spagnolo (es). I template personalizzati possono essere salvati per qualsiasi codice locale (per esempio pt-BR) tramite il selettore lingua dell’editor.

All’invio, Auris risolve il template in questo ordine:

1. Template personalizzato nella lingua del destinatario
2. Template personalizzato in inglese
3. Default integrato nella lingua del destinatario
4. Default integrato in inglese

Puoi quindi personalizzare solo le lingue che ti interessano — le altre continuano a funzionare con i default.

Passo 5: Anteprima

L’anteprima live renderizza il template con dati di esempio realistici mentre modifichi (per esempio [email protected] per {{email}} e 24 hours per {{expiresIn}}). Usa il selettore dispositivo per controllare le larghezze desktop, tablet e mobile, oppure apri l’anteprima a schermo intero.

Passo 6: Invia un’Email di Test

Clicca Invia test nell’editor. Auris renderizza il template con dati di esempio e lo invia al tuo indirizzo email (l’amministratore autenticato), con l’oggetto prefissato da [TEST]. Via API puoi opzionalmente specificare un destinatario diverso con il campo recipientEmail.

Controlla l’email nella tua casella e verifica:

• Il logo e le immagini si caricano correttamente
• Il pulsante d’azione è cliccabile e con lo stile giusto
• Il layout è corretto su desktop e mobile
• Tutti i placeholder sono stati sostituiti (nessun {{testo}} letterale)
• L’email non finisce nella cartella spam

Passo 7: Salva

Clicca Salva per pubblicare. Le modifiche hanno effetto immediato per tutte le email future di quel tipo e di quella lingua — nessun deploy o riavvio necessario. L’HTML salvato viene sanificato lato server (script, gestori di eventi e frame incorporati vengono rimossi) e deve restare sotto i 500 KB.

Per tornare al template predefinito della lingua corrente, clicca Ripristina default. Questo elimina la versione personalizzata e ripristina il template integrato con il branding del tenant.

Consegna delle Email

Auris invia le email tramite la configurazione SMTP del tuo tenant quando presente e attiva; in caso contrario usa il mittente predefinito della piattaforma. Puoi configurare SMTP (host, porta, credenziali, indirizzo mittente), eseguire un test di connessione e controllare il footer delle email da Impostazioni, poi Email:

• Email white-label rimuove l’attribuzione “Powered by Altovar” dal footer dei template predefiniti.
• Nascondi footer omette del tutto la fascia del footer.

Per la deliverability, configura i record DNS SPF, DKIM e DMARC per il tuo dominio mittente — il tuo provider email fornisce i valori esatti.

Gestione Programmatica dei Template

Tutte le operazioni disponibili in Console possono essere eseguite anche via API Template Email. Tutti gli endpoint richiedono il permesso manage:security e l’header x-tenant.

Elenca tutti i template

curl https://auth.tuodominio.com/api/email-templates \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: tuo-realm"

Restituisce ogni tipo con label, description, variables, hasCustomTemplate, customLocales, più availableLocales (le cinque lingue integrate).

Ottieni un template (con baseline predefinita)

curl "https://auth.tuodominio.com/api/email-templates/verification?locale=it" \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: tuo-realm"

Restituisce subject/htmlBody personalizzati per quella lingua (o null), insieme a defaultSubject/defaultHtmlBody renderizzati con il branding del tenant.

Aggiorna un template

curl -X PUT https://auth.tuodominio.com/api/email-templates/verification \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: tuo-realm" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Verifica la tua email",
    "htmlBody": "<!DOCTYPE html><html><body><p>Ciao {{email}},</p><p><a href=\"{{link}}\">Verifica il tuo indirizzo</a> — scade tra {{expiresIn}}.</p></body></html>",
    "locale": "it"
  }'

Anteprima di un template

curl -X POST https://auth.tuodominio.com/api/email-templates/verification/preview \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: tuo-realm" \
  -H "Content-Type: application/json" \
  -d '{ "subject": "Verifica la tua email", "htmlBody": "<p>Ciao {{email}}</p>" }'

Restituisce { "subject": ..., "html": ..., "variables": { ... } } renderizzati con valori di esempio. Non viene inviato nulla.

Invia un’email di test

curl -X POST https://auth.tuodominio.com/api/email-templates/verification/test \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: tuo-realm" \
  -H "Content-Type: application/json" \
  -d '{ "subject": "Verifica la tua email", "htmlBody": "<p>Ciao {{email}}</p>", "recipientEmail": "[email protected]" }'

recipientEmail è opzionale — senza, il test va alla tua casella (quella dell’amministratore autenticato). La risposta è { "success": true, "sentTo": "..." }.

Elimina (ripristina il default)

curl -X DELETE "https://auth.tuodominio.com/api/email-templates/verification?locale=it" \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: tuo-realm"

Con ?locale= viene eliminata solo la versione personalizzata di quella lingua. Senza, vengono eliminate tutte le lingue del tipo.

Buone Pratiche

Mantieni i template semplici. Il supporto HTML dei client email è notoriamente incoerente. Usa stili inline, layout a tabelle e font di sistema per la massima compatibilità.

Includi sempre l’URL d’azione in chiaro. Sotto ogni pulsante d’azione, riporta l’URL grezzo come testo. Alcuni client non renderizzano correttamente i pulsanti HTML, e alcuni utenti preferiscono ispezionare gli URL prima di cliccare. Auris deriva automaticamente anche una parte text/plain dal tuo HTML, preservando i link.

Usa {{expiresIn}} per gestire le aspettative. Dì sempre all’utente per quanto tempo un link o un codice è valido.

Mantieni il pulsante di approvazione condizionale in magic_link. Racchiudi il pulsante secondario in {{#if approveLink}}...{{/if}} — la variabile è vuota per i flussi che non usano l’approvazione cross-device, e il condizionale rimuove il pulsante in modo pulito.

Non includere dati sensibili. Mai inserire password o chiavi API complete nelle email. Le email possono restare nelle caselle degli utenti a tempo indeterminato.

Versiona i tuoi template. Se gestisci i template via API, conserva l’HTML sorgente nel tuo repository: ottieni cronologia, review e rollback.

Risoluzione dei Problemi

Guide Correlate

• Template Email (Console) — Riferimento dell’editor e catalogo dei template
• API Template Email — Riferimento completo degli endpoint
• Branding — Branding del tenant applicato alle email predefinite
• Login con Magic Link — Il flusso dietro il template magic_link