TrattoDocumentazione
HomeDocumentazioneBlog
ENIT
Inizia ora

Template: Crea, Versiona e Test

Gestisci template email versionati con sostituzione di variabili

I template sono template email riutilizzabili con variabili placeholder. Invece di comporre HTML nel codice ogni volta, definisci un template una volta e invialo centinaia di volte con variabili diverse.

Due Formati: HTML e Markdown

Ogni template ha un format, scelto alla creazione e immutabile dopo:

  • html (default) — l'HTML dell'email lo fornisci tu. Tutto in questa pagina usa questo formato.
  • emailmd — fornisci markdown nel campo markdown; il server lo renderizza in HTML responsive ed email-safe al salvataggio e memorizza il markdown come source. Il campo html della risposta è l'output renderizzato e non può essere impostato direttamente (inviare html per questo formato fallisce con 422). Un endpoint stateless POST /v1/templates/render-preview renderizza il markdown senza salvare.

I template markdown hanno una guida dedicata — sintassi, modello di sicurezza, flusso end-to-end: Template Markdown. Le risposte in questa pagina omettono il campo format per brevità; i template creati prima dell'esistenza dei formati sono html.

Crea un Template

Un template è un nome più un corpo. La richiesta accetta name, format e uno fra html e markdown — nient'altro.

Un template non ha un oggetto. Non esiste un campo subject sul template, né un campo text che tu possa impostare: l'oggetto appartiene al singolo invio. Passarlo in questa richiesta non ha alcun effetto — viene scartato in silenzio, non memorizzato.

cURL

curl -X POST https://api.tratto.email/v1/templates \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Email di Benvenuto",
    "html":"<h1>Benvenuto, {{firstName}}!</h1><p>Il tuo codice: {{code}}</p>"
  }'

Risposta:

{
  "data": {
    "id": "tmpl_abc123",
    "name": "Email di Benvenuto",
    "html": "<h1>Benvenuto, {{firstName}}!</h1><p>Il tuo codice: {{code}}</p>",
    "status": "draft",
    "version": 1,
    "createdAt": "2025-06-30T12:00:00Z",
    "updatedAt": "2025-06-30T12:00:00Z"
  }
}

status è un'etichetta, non un gate

Un template nasce con status: "draft", e status accetta draft o published. Finisce lì: è un'etichetta editoriale per il tuo flusso di lavoro, e l'API non la fa rispettare in alcun modo.

Un template draft si invia. Il percorso di consegna carica il template e ne legge l'html: non guarda mai status. Se ti serve che «non pronto per l'invio» significhi davvero questo, imponilo nel tuo codice — non contare sul rifiuto dell'API.

Cambia l'etichetta come qualsiasi altro campo:

cURL

curl -X PATCH https://api.tratto.email/v1/templates/tmpl_abc123 \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{"status":"published"}'

È anche un filtro sull'endpoint di elenco: GET /v1/templates?status=published.

Invia Usando un Template

Il template fornisce il corpo. subject è obbligatorio sull'invio e va passato ogni volta: se lo ometti la richiesta fallisce con 422.

cURL

curl -X POST https://api.tratto.email/v1/emails \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from":"[email protected]",
    "to":"[email protected]",
    "subject":"Benvenuta, {{firstName}}!",
    "templateId":"tmpl_abc123",
    "variables":{
      "firstName":"Alice",
      "code":"SECRET123"
    }
  }'

Risultato:

Subject: Benvenuta, Alice!
HTML: <h1>Benvenuto, Alice!</h1><p>Il tuo codice: SECRET123</p>

L'oggetto viene renderizzato con le stesse variables del corpo, quindi {{firstName}} funziona in entrambi. Una variabile che non passi diventa una stringa vuota anche nell'oggetto — vedi Passa Sempre Tutte le Variabili più sotto.

Un template html non ha una parte testuale. Un template Markdown fissa al salvataggio una parte testuale renderizzata, e quella viene inviata come text/plain accanto all'HTML.

Aggiorna un Template

Aggiorna un template. Questo crea una nuova versione, lasciando intatte le versioni precedenti.

cURL

curl -X PATCH https://api.tratto.email/v1/templates/tmpl_abc123 \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "html":"<h1>Benvenuto di nuovo, {{firstName}}!</h1><p>Codice: {{code}}</p>"
  }'

Risposta: il template completo, con version incrementata.

{
  "data": {
    "id": "tmpl_abc123",
    "name": "Email di Benvenuto",
    "html": "<h1>Benvenuto di nuovo, {{firstName}}!</h1><p>Codice: {{code}}</p>",
    "status": "draft",
    "version": 2,
    "createdAt": "2025-06-30T12:00:00Z",
    "updatedAt": "2025-06-30T12:05:00Z"
  }
}

La versione si incrementa solo se il contenuto cambia davvero: una PATCH che reimposta lo stesso HTML la lascia com'è. Le versioni non hanno uno status proprio, e il bump di versione non tocca lo status del template.

Per i template Markdown, aggiorna invece il campo markdown — ogni modifica ri-renderizza l'HTML e incrementa la versione allo stesso modo. html e markdown sono mutuamente esclusivi in una PATCH, e ciascuno è accettato solo da un template del formato corrispondente (422 altrimenti).

Cronologia delle Versioni

Elenca le versioni di un template, dalla più recente (fino a 20). Ogni voce contiene solo il numero di versione e il momento del salvataggio:

cURL

curl https://api.tratto.email/v1/templates/tmpl_abc123/versions \
  -H "Authorization: Bearer tratto_live_..."

Risposta:

{
  "data": [
    { "version": 2, "savedAt": "2025-06-30T12:05:00Z" },
    { "version": 1, "savedAt": "2025-06-30T12:00:00Z" }
  ]
}

Ottieni una Versione

Per leggere il contenuto di una versione passata — l'unico modo di recuperarlo — richiedila per numero:

cURL

curl https://api.tratto.email/v1/templates/tmpl_abc123/versions/1 \
  -H "Authorization: Bearer tratto_live_..."

Risposta:

{
  "data": {
    "version": 1,
    "html": "<h1>Benvenuto, {{firstName}}!</h1><p>Il tuo codice: {{code}}</p>",
    "savedAt": "2025-06-30T12:00:00Z"
  }
}

Su un template Markdown la risposta porta anche source: il markdown che ha prodotto l'HTML di quella versione.

Invio di Test

Invia un'email di test usando il template per verificare che appaia corretta.

cURL

curl -X POST https://api.tratto.email/v1/templates/tmpl_abc123/test-send \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to":"[email protected]",
    "variables":{
      "firstName":"Alice",
      "code":"TEST123"
    }
  }'

Un'email di test viene inviata immediatamente al tuo indirizzo in modo che tu possa esaminarla nella tua inbox.

Il suo oggetto è [Test] seguito dal nome del template. Un invio di test non ha un contatto, quindi le variabili del destinatario che non passi prendono valori di anteprima: email è l'indirizzo di test, firstName è Preview, lastName è Recipient e unsubscribe_url è un link di anteprima che non disiscrive nessuno. Ogni altra variabile che ometti diventa vuota, come in un invio reale.

Elenca i Template

Ottieni tutti i template per il tuo tenant.

cURL

curl https://api.tratto.email/v1/templates \
  -H "Authorization: Bearer tratto_live_..."

Ottieni un Template

Recupera un template specifico.

cURL

curl https://api.tratto.email/v1/templates/tmpl_abc123 \
  -H "Authorization: Bearer tratto_live_..."

Elimina un Template

Elimina permanentemente un template (non può essere annullato).

cURL

curl -X DELETE https://api.tratto.email/v1/templates/tmpl_abc123 \
  -H "Authorization: Bearer tratto_live_..."

L'eliminazione di un template non può essere annullata. Le campagne e i flussi che usano quel template falliranno.

Sintassi Variabile del Template

Usa le doppie graffe {{variableName}} per i placeholder — gli spazi attorno sono ammessi, quindi funziona anche {{ firstName }}. Le variabili fanno distinzione tra maiuscole e minuscole. Non ci sono condizioni né cicli: è sostituzione, non un linguaggio di template.

Template:

HTML: <p>Ciao {{firstName}}, la tua email è {{email}}</p>

Invio:

{
  "variables": {
    "firstName": "Alice",
    "email": "[email protected]"
  }
}

Renderizzato:

HTML: <p>Ciao Alice, la tua email è [email protected]</p>

La sostituzione si applica all'oggetto e ai corpi HTML e testo.

Best Practice

1. Usa Nomi Variabili Semantici

✅ {{firstName}}, {{orderID}}, {{confirmationCode}}
❌ {{x}}, {{var1}}, {{v}}

2. Passa Sempre Tutte le Variabili

Una variabile mancante non fa fallire l'invio: il placeholder viene sostituito con una stringa vuota. Questo template

<p>Ciao {{firstName}}, benvenuto a {{companyName}}!</p>

inviato senza firstName né companyName arriva come Ciao , benvenuto a ! — la punteggiatura resta orfana, ma il destinatario non vede mai il nome della tua variabile.

Vale per l'oggetto e per il corpo, in HTML e in Markdown, sia sugli invii transazionali che sulle campagne. Anche null sostituisce vuoto: non comparirà mai la stringa null o undefined in un'email.

Non è un invito a passare meno variabili — al contrario. Una frase con un buco resta una frase sbagliata, e ora niente te lo segnala: né all'invio, né prima. Con il placeholder visibile un refuso come {{firstname}} al posto di {{firstName}} almeno si notava nell'anteprima; con la sostituzione vuota sparisce senza lasciare traccia.

Il controllo automatico esiste solo per le campagne, dove Tratto conosce l'insieme delle variabili disponibili (email, firstName, lastName, unsubscribe_url) e può quindi segnalare in bozza quelle che non ne fanno parte. Per un template non è possibile: le variabili arrivano da chi chiama POST /v1/emails, quindi non esiste un insieme contro cui verificarle e ogni controllo sarebbe un'ipotesi.

Su un template, quindi, l'unica difesa è passare a ogni invio tutti i placeholder che il template usa.

3. Usa Template per Invii Bulk

Non comporre HTML per ogni email. Usa template e variabili per consistenza e riutilizzabilità.

4. Fai un Test Prima di Usarlo

Fai sempre un test-send del template prima di inviarlo a qualcuno, per intercettare problemi di rendering. Nulla impedisce a un template draft di partire: il test-send è l'unico controllo che esiste.

Prossimi Passi

Modifica questa pagina su GitHub

Ultimo aggiornamento

Invia Email

L'endpoint principale per inviare email tramite Tratto

Template Markdown

Scrivi i template email in markdown e lascia che Tratto generi HTML responsive ed email-safe per te.

In questa pagina

Due Formati: HTML e Markdown
Crea un Template
status è un'etichetta, non un gate
Invia Usando un Template
Aggiorna un Template
Cronologia delle Versioni
Ottieni una Versione
Invio di Test
Elenca i Template
Ottieni un Template
Elimina un Template
Sintassi Variabile del Template
Best Practice
1. Usa Nomi Variabili Semantici
2. Passa Sempre Tutte le Variabili
3. Usa Template per Invii Bulk
4. Fai un Test Prima di Usarlo
Prossimi Passi