Sign inGet Started
Inizia ora
Guide
Riferimento API
SDK
CLI
Knowledge Base
Changelog

Template email

Un template è un oggetto e un corpo email che salvi una volta e invii molte volte. Scrivi le parti variabili come segnaposto {{ variable }}, pubblichi il template e poi lo invii tramite slug invece di incollare lo stesso HTML in ogni chiamata API. Un template appartiene al tuo spazio di lavoro.
Crea e gestisci i template in Email > Templates, tramite /v1/email/templates, con il bird CLI, oppure tramite il server MCP. I metodi tipizzati sono disponibili negli SDK TypeScript, Python, PHP e Go sotto email.templates. Gli schemi completi di richiesta e risposta sono nel reference API. Invia un template pubblicato tramite il normale endpoint di invio.

Cosa contiene un template

Ogni template ha due nomi, e svolgono funzioni diverse:
  • slug è il nome con cui invii il template, ad esempio welcome-email. Lo scegli quando crei il template e non può essere cambiato in seguito. Uno slug può contenere lettere minuscole, numeri, trattini e underscore, deve iniziare e finire con una lettera o un numero e può essere lungo fino a 63 caratteri. Due prefissi non sono utilizzabili: bird_, riservato ai nostri template integrati, e emt_, che è il formato usato per gli ID dei template. La dashboard chiama questo campo Alias.
  • name è un'etichetta di visualizzazione a testo libero. Per impostazione predefinita corrisponde allo slug e puoi cambiarla in qualsiasi momento. Nulla viene risolto tramite il nome, quindi rinominare un template a scopo di visualizzazione non interrompe mai un invio.
Oltre a questi, un template ha un ID emt_ permanente, fisso per tutta la sua vita. Ha anche una category, che può essere marketing o transactional, e un source di authoring: html, markup finito che fornisci tu, opzionalmente personalizzato con Liquid. La categoria e la sorgente sono entrambe fissate quando crei il template.
Forniamo un catalogo di template integrati, i cui slug iniziano tutti con bird_. Un template integrato non appartiene a nessuno spazio di lavoro, non può essere modificato ed è sempre pronto per l'invio così com'è. Copiandone uno nel tuo spazio di lavoro lo rendi tuo e diventa un template ordinario che puoi modificare. La copia arriva come bozza non pubblicata che eredita la categoria, la sorgente e le impostazioni di lingua dell'originale, quindi pubblicala prima di inviarla.

Bozze e versioni pubblicate

Ogni template ha esattamente una bozza, cioè la copia di lavoro che modifichi. Ha inoltre un numero qualsiasi di versioni pubblicate, ciascuna numerata (1, 2, 3 e così via) e mai più modificata una volta creata. Le modifiche cambiano la bozza sul posto. La pubblicazione acquisisce uno snapshot della bozza corrente, lo trasforma nella versione numerata successiva e rende quella versione quella usata dagli invii. La bozza stessa resta modificabile, così puoi continuare a lavorare alla successiva.
La regola che conta per l'invio è questa: un invio usa sempre la versione pubblicata del template, e una bozza non viene mai inviata da sola. Puoi continuare a modificare la bozza mentre una versione stabile continua a uscire, e poi pubblicare quando la modifica è pronta. Pubblicare una nuova versione cambia ciò che gli invii successivi renderizzano. Un invio già accettato non è influenzato da una pubblicazione avvenuta dopo.
La scheda Versioni del template con una riga Bozza e le righe pubblicate v3, v2 e v1 che mostrano le date di creazione e pubblicazione
Le versioni supportano altre due azioni. Scarta le modifiche della bozza per ripristinare la bozza allo stato della versione attualmente pubblicata. Oppure ripristina una versione precedente per rendere una versione pubblicata precedente quella usata dagli invii. Puoi ripristinare solo una versione che è stata pubblicata, mai la bozza stessa. Il ripristino sostituisce la bozza con il contenuto di quella versione, quindi tutto ciò che non è stato salvato nella bozza va perso, e le modifiche successive partono dalla versione ripristinata. Un ripristino non crea una nuova versione.
Per scegliere un’immagine esistente, devi avere accesso in lettura alla libreria multimediale dello spazio di lavoro. Per caricare, incollare o trascinare una nuova immagine, devi avere accesso in scrittura. Se Inserisci immagine è disabilitato o non puoi sfogliare la libreria o caricare immagini, chiedi a un amministratore dello spazio di lavoro il permesso corrispondente per la libreria multimediale. Il solo permesso di modificare i template non dà accesso alla libreria multimediale.
Nella dashboard, scegli Visuale > Inserisci immagine per cercare nella libreria multimediale o caricare un’immagine PNG, JPEG, GIF o WebP fino a 5 MB. Le immagini WebP statiche vengono convertite in PNG o JPEG. Seleziona l’immagine per impostarne la Descrizione dell’immagine, la larghezza di visualizzazione, l’allineamento e il link. Contrassegnala come Immagine decorativa solo se non aggiunge informazioni; un’immagine con link richiede una descrizione che ne spieghi la destinazione. Ogni lingua mantiene le proprie descrizioni delle immagini e il proprio layout.
Usa Sostituisci immagine per cambiare l’immagine selezionata mantenendone descrizione, link, larghezza e allineamento. Puoi anche incollare o trascinare un file immagine alla volta nell’editor visuale. Attendi che il caricamento termini, oppure annullalo, prima di salvare o inviare una prova. Controlla l’anteprima, quindi apri Altre azioni > Email di prova per inviarti il contenuto attuale. Codice rimane disponibile per modificare l’HTML.
Rimuovere un’immagine dalla libreria multimediale non la rimuove dalle email già inviate. La sostituzione di un’immagine usa un nuovo URL, quindi i messaggi precedenti continuano a mostrare l’originale.
Il salvataggio è protetto da un numero di revisione. Invia il revision che hai letto per ultimo per la lingua che stai salvando. Se qualcun altro ha modificato quella lingua nel frattempo, il salvataggio viene rifiutato come conflitto invece di sovrascrivere il suo lavoro. Ometti revision per salvare incondizionatamente. La pubblicazione e il ripristino usano il revision della bozza allo stesso modo.

Contenuto in più lingue

Un template contiene contenuto in un massimo di 25 lingue, ciascuna con il proprio oggetto e corpo, contrassegnata con un codice BCP-47 come en o pt-BR. Una lingua è quella predefinita del template. La pubblicazione di un template pubblica tutte le lingue che contiene contemporaneamente. Non puoi pubblicare una sola lingua, quindi devono essere tutte completate prima. Ogni lingua ha bisogno di un oggetto e di un corpo, e la lingua predefinita del template deve essere una delle lingue che hai compilato. Se manca qualcosa, nulla viene pubblicato e l'errore indica cosa manca in ciascuna lingua, così puoi correggere tutto in un solo passaggio. Non devi completare tutte le lingue subito: pubblica quelle pronte e aggiungi le altre in seguito.
Una lingua ha bisogno di un corpo HTML. Puoi omettere il suo text: la pubblicazione crea automaticamente un'alternativa in testo semplice dall'HTML, così ottieni entrambe le parti senza scrivere la seconda tu stesso.
Ogni lingua può anche avere un testo di anteprima, a volte chiamato preheader: la riga che un client di posta mostra dopo l'oggetto nell'elenco dei messaggi. È opzionale, lungo fino a 255 caratteri, e accetta gli stessi segnaposto {{ variable }} dell'oggetto. Se lo ometti, il client di posta ripiegherà sulla prima riga del corpo, che raramente è quella che sceglieresti. La pubblicazione rifiuta il testo di anteprima su una lingua il cui corpo non ha una parte HTML, perché un client di posta legge la riga di anteprima solo dal markup HTML nascosto, e rifiuta {{ bird.unsubscribe_url }} al suo interno per la stessa ragione per cui l'oggetto non può contenerlo: nessuno dei due è un posto in cui può andare un link.
Due impostazioni coprono un invio che non specifica una lingua per cui il template ha contenuto, e proteggono da errori diversi:
ImpostazioneCosa controlla
on_missing_languageCosa succede quando un invio richiede una lingua che il template non ha. fallback, il valore predefinito, serve la corrispondenza più vicina. Prova prima una forma più ampia della stessa lingua, così un pt memorizzato può servire una richiesta per pt-BR. Poi ripiegherà sulla lingua predefinita del template. fail rifiuta l'invio, per contenuti in cui inviare la lingua sbagliata è peggio che non inviare affatto.
language_source_requiredSe un invio deve indicare una lingua. L'impostazione è disattivata per impostazione predefinita, quindi un invio che non ne indica nessuna riceve la lingua predefinita. Attivandola, l'invio viene invece rifiutato. Un broadcast indica una sola lingua per tutto il pubblico, quindi un template con questa impostazione attiva richiede che la lingua sia scelta prima che il broadcast possa partire.
Puoi impostare queste due opzioni in modo indipendente. Da solo, fail si applica solo quando un invio specifica una lingua che non abbiamo, quindi un invio che non ne specifica nessuna passa comunque. Attiva entrambe le impostazioni insieme quando vuoi che ogni invio specifichi una lingua intenzionalmente.

Personalizzazione con le variabili

Scrivi segnaposto {{ variable }} nell'oggetto, nel testo di anteprima e nel corpo. Li rileviamo automaticamente, combinati su tutte le lingue, quindi non devi mai dichiararli separatamente. Il prefisso del segnaposto distingue i due tipi. Un percorso che inizia con bird. legge dai nostri dati, un record di contatto o il link di disiscrizione. Tutto il resto è un parametro a cui dai un valore quando invii.
Il nome di un parametro è una singola parola, come {{ animal }}. Un nome puntato cerca una struttura che un parametro non ha, quindi la pubblicazione viene rifiutata: scrivi il valore come parametro a sé stante, oppure leggi i dati del contatto con bird.contact.<attribute>.
In un invio singolo o un batch, il valore di un parametro viene dall'oggetto template.parameters dell'invio, indicizzato per nome. Un unico set di valori copre tutti i destinatari di quell'invio. bird è l'unico nome che non puoi usare lì: una chiave template.parameters chiamata bird viene rifiutata con un 422.
Un broadcast non ha un oggetto parameters, quindi il suo contenuto può usare solo segnaposto bird.. bird.contact.<attribute> viene compilato dalle proprietà del contatto di ciascun destinatario, ed è questo che personalizza il contenuto per destinatario. Ogni proprietà del contatto è disponibile tramite la propria chiave, così come i tre campi integrati: first_name, last_name e email.
Esempio di codice
Hi {{ bird.contact.first_name }},
Ogni parametro nel template ha bisogno di un valore quando invii. Altrimenti, API restituisce un 422 che indica il parametro mancante. Fornisci i valori per i parametri in tutte le lingue, perché la lingua selezionata può dipendere dalle impostazioni di fallback. Una proprietà del contatto mancante viene renderizzata come valore vuoto, quindi aggiungi un fallback per il contenuto visibile al cliente: {{ bird.contact.first_name | default: "there" }}.
Un broadcast è più rigido sui nomi che accetta, perché le proprietà del contatto sono l'unica fonte per riempire i segnaposto. I suoi segnaposto bird.contact.* possono indicare solo un campo predefinito o una proprietà del contatto registrata nello spazio di lavoro. Qualsiasi altro segnaposto, incluso un parametro, non ha modo di essere riempito dal broadcast. L'invio viene rifiutato e l'errore indica il segnaposto.
Ciò che archiviare una proprietà cambia per un template riguarda solo i nuovi contenuti: la proprietà scompare dal selettore nell'editor, e la pubblicazione di una versione il cui contenuto la legge viene rifiutata, indicando la proprietà. Le versioni pubblicate prima dell'archiviazione non sono interessate.
I segnaposto usano Liquid, quindi filtri e flussi di controllo funzionano insieme alla semplice sostituzione. Un condizionale {% if %} e un ciclo {% for %} su un valore array vanno entrambi bene. Alcuni costrutti vengono rifiutati alla pubblicazione, e l'errore indica esattamente cosa modificare:
  • Inclusioni parziali, con {% include %} o {% render %}.
  • I tag increment, decrement e ifchanged.
  • I filtri money, format_date, format_time, json, inspect e type.
  • Confronti con empty o blank. Usa .size == 0 al loro posto.
  • Blocchi annidati molto più in profondità di quanto richieda un vero markup email.
Il template di un broadcast non può usare un ciclo {% for %}, perché un broadcast inserisce un solo valore per proprietà del contatto e non ha nulla su cui iterare. Se il tuo contenuto ha bisogno di un ciclo, invialo tramite l'endpoint API dei messaggi.
Ogni template usa Liquid, anche uno che contiene solo segnaposto {{ variable }}. Prima della pubblicazione, validiamo oggetto, testo di anteprima, HTML e contenuto in testo semplice come Liquid. Aggiungiamo anche il filtro escape a ogni output HTML che non termina già con escape o escape_once, così un valore che contiene & o < non può alterare il markup circostante. L'output riservato per la disiscrizione resta invariato perché l'invio possa sostituirlo. L'oggetto e il corpo in testo semplice restano come scritti. Poiché la pubblicazione aggiunge questi filtri, l'HTML che leggi da una versione pubblicata potrebbe non essere identico byte per byte a quello che hai inviato.
Inserisci un URL completo direttamente in un href, ad esempio <a href="{{ sign_in_url }}">Sign in</a>. Non aggiungere url_encode all'intero valore. Codifica in percentuale https://, /, ? e &, impedendo al risultato di funzionare come link assoluto. L'escaping HTML viene aggiunto preservando la struttura dell'URL. Quando un parametro fornisce un singolo componente dell'URL, codifica quel componente esplicitamente: <a href="https://example.com/search?q={{ query | url_encode }}">Search</a>.

Anteprima prima della pubblicazione

Renderizza un template con valori di esempio e ottieni l'oggetto e i corpi HTML e testo semplice che un invio consegnerebbe. L'anteprima usa il nostro renderer Liquid locale e renderizza la bozza per impostazione predefinita: è il modo per verificare una modifica prima che vada in produzione. Può renderizzare anche una versione pubblicata. Funziona sia con i tuoi template sia con quelli predefiniti, e non viene inviato nulla.
Puoi anche passare direttamente il contenuto invece di farlo leggere dalla bozza. Fornisci un oggetto e i corpi: vengono renderizzati esattamente come una bozza, il che permette a un editor di mostrare una modifica mentre viene digitata senza salvare nulla prima.
La personalizzazione viene compilata per te, quindi il risultato si legge come testo finito anziché come segnaposto {{ }}. Indica un contact e ogni bird.contact.<attribute> viene risolto rispetto alle proprietà di quel contatto: è il modo per verificare la formulazione su un record reale prima che qualcuno lo riceva. I valori provengono dalla stessa proiezione che un broadcast usa per riempire i suoi segnaposto, quindi l'anteprima risponde con ciò che risponderebbe un invio.
Ometti contact e vengono sostituiti valori segnaposto: Bird e Test per nome e cognome, bird.test@example.com per l'email e il fallback registrato di ogni altra proprietà. Una proprietà referenziata senza fallback viene resa come la sua chiave tra parentesi, ad esempio [loyalty_tier], il che indica sia che il valore è un segnaposto sia quale proprietà necessita ancora di un fallback.
Un contatto viene letto così com'è in questo momento. Questo rende l'anteprima lo strumento giusto per controllare il contenuto che stai per inviare, e quello sbagliato per sapere cosa conteneva un invio precedente. Per leggere cosa ha effettivamente consegnato un invio, apri quel messaggio nel log email, che lo renderizza a partire dai valori che quell'invio portava con sé.
Aggiungi language per renderizzare una lingua specifica, oppure omettilo per la lingua predefinita del template. La risposta indica quale lingua è stata renderizzata, il che conta quando quella richiesta non è disponibile e il on_missing_language del template ha servito una corrispondenza prossima.
Se la bozza contiene personalizzazioni che verrebbero rifiutate alla pubblicazione, l'anteprima restituisce lo stesso errore, quindi funziona anche come modo per individuare problemi in anticipo.
Nel template builder della dashboard, Preview with contact data in fondo alla barra laterale sinistra mostra l'email renderizzata accanto a ciò che stai modificando, sia nell'editor visuale sia in quello del codice. Il selettore sottostante sceglie i dati di quale contatto riempiono i segnaposto, e Sample data corrisponde ai valori segnaposto descritti sopra.

Invio con un template

Imposta il campo template dell'invio su un oggetto che indica il template, tramite id (emt_...) oppure tramite slug, usando esattamente uno dei due. Inserisci i valori delle variabili in template.parameters. Aggiungi language per scegliere una lingua specifica, oppure omettilo per inviare nella lingua predefinita del template, a meno che il template richieda che ogni invio ne indichi una. Ometti del tutto subject, html e text, perché il template li fornisce già.
Esempio di codice
{
  "from": "hello@yourdomain.com",
  "to": ["delivered@messagebird.dev"],
  "category": "transactional",
  "template": {
    "slug": "welcome-email",
    "parameters": { "first_name": "Jane" }
  }
}
Un comportamento da prevedere: la categoria del template è un valore predefinito, e il category dell'invio la sovrascrive. Ometti category e l'invio eredita la categoria del template, quindi un template operativo viene inviato come transazionale senza doverlo ripetere a ogni chiamata. Imposta category e il tuo valore prevale. Il resto del contratto lato invio è in invio con un template.

Creazione al di fuori della dashboard

L'intero ciclo di vita è disponibile al di fuori della dashboard. Il passaggio di pubblicazione si chiama submit, ed è l'operazione che trasforma la bozza nella versione pubblicata successiva:
Esempio di codice
bird email templates create welcome-email --category marketing --source html
bird email templates versions languages set <emt_...> <emv_...> en --subject "Hi {{ bird.contact.first_name }}" --html "<p>Hello</p>"
bird email templates versions submit <emt_...> <emv_...> --validate-only   # report problems, freeze nothing
bird email templates versions submit <emt_...> <emv_...>                   # freeze, go live
create restituisce il template insieme al suo draft_version_id, necessario per ogni comando di versione e lingua. --validate-only esegue gli stessi controlli di completezza di un vero submit, senza bloccare nulla, quindi è il modo rapido per trovare ogni problema in tutte le lingue in un solo passaggio. Rileggere un template restituisce i suoi metadati e lo stato per lingua, ma non il contenuto. Il contenuto si trova nelle lingue di una versione, una lingua alla volta.
Gli SDK offrono lo stesso ciclo di vita come metodi tipizzati sotto email.templates, con le operazioni di versione e lingua annidate come email.templates.versions e email.templates.versions.languages. Un agente raggiunge le stesse operazioni tramite i tool email_templates_* MCP.

Prossimi passi

  • Invio di email: il payload completo dell'invio e come si integrano gli invii con template
  • Categorie: scegliere marketing o transactional per ogni invio
  • bird email templates: gestire i template dal terminale
  • Reference API: schemi completi di richiesta e risposta per tutte le diciotto operazioni sui template
  • SDK: i metodi tipizzati email.templates in TypeScript, Python, PHP e Go
  • Server MCP: consentire a un agente di creare e pubblicare template
  • Come creare un template email: un video che ne costruisce uno nella dashboard e poi ne fa costruire un altro a un agente

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Esplora la funzionalitàEmail templatesSegui il percorso di apprendimentoBuild your first integration
Prova l'esercitazione e ottieni un brief di implementazione